Google Ads MCP 서버: 개발자 통합 가이드

모델 컨텍스트 프로토콜 (MCP) 은 대규모 언어 모델 (LLM)이 외부 데이터 및 애플리케이션과 안전하게 상호작용할 수 있도록 지원하는 개방형 표준입니다. Google Ads MCP 서버 는 Google Ads API에 대한 표준화된 브리지를 제공하여 AI 에이전트가 자연어를 사용하여 캠페인 데이터를 분석하고 검색할 수 있도록 합니다.

커뮤니티 리소스 및 지원

기술 개요

이 MCP 서버를 구현하면 Google Ads API 인증, 리소스 가져오기, 데이터 파싱을 위한 맞춤 '접착 코드'를 작성할 필요가 없습니다. 서버는 LLM이 자율적으로 검색하고 호출할 수 있는 특정 도구 를 노출합니다.

주요 사양

  • 프로토콜: MCP (모델 컨텍스트 프로토콜)
  • 모드: 읽기 전용 (현재 버전)
  • 언어: Python
  • 전송: 표준 입력/출력 (stdio)
  • 인증: OAuth 2.0 또는 서비스 계정

상호작용 루프 작동 방식

  1. 요청: 사용자가 "이번 주 캠페인 실적은 어떻게 되나요?"와 같은 쿼리를 제출합니다.
  2. 검색: LLM은 사용 가능한 도구를 검사하고 google-ads-mcp 검색 기능을 식별합니다.
  3. 실행: MCP 서버는 기본 Python 로직을 실행하여 Google Ads API를 쿼리합니다.
  4. 컨텍스트 삽입: 구조화된 결과가 LLM의 컨텍스트 창으로 반환됩니다.
  5. 응답: LLM은 데이터를 종합하여 사람이 읽을 수 있는 답변을 생성합니다.

시작하기

다음 단계에 따라 Google Ads MCP 서버를 구성하고 사용합니다.

기본 요건

구성을 시작하기 전에 Google Cloud 콘솔에서 다음 사용자 인증 정보가 있는지 확인하세요.

구성

서버를 MCP 호환 호스트에 통합하려면 호스트의 MCP 구성 파일(예: settings.json)에 다음 항목을 추가합니다. 이 구성의 정확한 위치와 파일 이름은 호스트의 문서를 참고하세요.

JSON

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}

Google Cloud에 배포

이 MCP 서버를 로컬에서 호스팅하는 대신 Google Cloud Run 또는 다른 클라우드 기반 인프라에서 호스팅할 수 있습니다. 이는 여러 에이전트 간에 서버를 공유하거나 웹 서비스로 운영하려는 경우에 유용합니다.

기본 요건

  1. Google Cloud 프로젝트

  2. gcloud 명령줄 도구가 설치되고 인증되었으며 활성 프로젝트가 구성되어 있습니다.

    gcloud config set project YOUR_PROJECT_ID

Docker 이미지 빌드 및 푸시

Cloud Build를 사용하면 Docker를 로컬에 설치하지 않고도 이미지를 빌드하고 Artifact Registry에 푸시할 수 있습니다.

  1. Artifact Registry에서 저장소를 만듭니다.

    gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1

  2. 프로젝트 디렉터리로 이동합니다.

    cd <full path>/google-ads-mcp

  3. 이미지를 빌드하고 제출합니다.

    gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    배포된 서버를 최신 버전으로 업데이트하려면 이 단계를 실행해야 합니다.

Google Cloud Run에 배포

필수 환경 변수를 설정해야 합니다.

  • GOOGLE_PROJECT_ID: 적절한 API 액세스 수준이 있는 Google Cloud 프로젝트 ID입니다.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: MCP 서버에서 사용할 OAuth 클라이언트 ID입니다.
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: MCP 서버에서 사용할 OAuth 클라이언트 보안 비밀번호입니다.
  • GOOGLE_ADS_MCP_BASE_URL: MCP 서버에 액세스할 수 있는 기본 URL입니다. 이는 첫 번째 배포 후 Google Cloud Run에서 자동으로 할당됩니다. 배포 후 환경 변수를 업데이트할 수 있습니다.
  • FASTMCP_HOST: FastMCP가 모든 IP 주소의 연결을 수락하도록 하려면 이 값을 0.0.0.0으로 설정합니다.
gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

MCP 클라이언트 구성

배포 후 Cloud Run URL을 사용하도록 MCP 클라이언트 구성 (예: ~/.gemini/settings.json)을 업데이트합니다.

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

핵심 기능 (도구)

서버는 계정 검색 및 실적 보고를 위해 설계된 도구를 노출합니다.

  • list_accessible_customers: 인증된 사용자가 액세스할 수 있는 Google Ads 고객 ID 및 계정 이름 목록을 반환합니다.
  • search: Google Ads Query Language (GAQL) 요청을 실행하여 리소스 측정항목, 예산, 상태를 가져옵니다.

  • get_resource_metadata: Google Ads API 리소스 유형(예: '캠페인')에 관한 메타데이터를 검색합니다.

    이는 데이터의 구조와 쿼리에 사용할 수 있는 필드를 이해하는 데 유용합니다.

시작을 위한 샘플 프롬프트

서버에서 할 수 있는 작업 묻기:

What can the google-ads-mcp server do?

고객에 관해 묻기:

What customers do I have access to?

캠페인에 관해 묻기:

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890