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

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

커뮤니티 리소스 및 지원

기술 개요

이 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 Ads 개발자 콘솔에서 다음 사용자 인증 정보가 있는지 확인하세요.

  • 개발자 토큰: 고유한 22자 액세스 문자열입니다.
  • 프로젝트 ID: Google Cloud 프로젝트 ID입니다.
  • OAuth 사용자 인증 정보: OAuth2 클라이언트 ID/클라이언트 보안 비밀번호 쌍 또는 애플리케이션 기본 사용자 인증 정보 집합입니다.

구성

서버를 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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

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. 이미지를 빌드하고 제출합니다.

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

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

Google Cloud Run에 배포

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

  • GOOGLE_PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • GOOGLE_ADS_DEVELOPER_TOKEN: MCP 서버에서 사용할 개발자 토큰 입니다.
  • 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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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"
    }
  }
}

주요 기능 (도구)

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

시작하기 위한 샘플 프롬프트

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

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