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

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

커뮤니티 리소스 및 지원

• GitHub 저장소: google-ads-mcp 저장소에서 데모와 예시를 찾고 버그를 신고하거나 기능을 제안하세요.

  버그 신고 및 기능 요청에는 문제 탭을 사용하세요.

• 커뮤니티: Google 광고 커뮤니티 Discord의 #ads-api-ai-tools 채널에 가입하세요.

기술 개요

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

주요 사양

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

상호작용 루프 작동 방식

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

시작하기

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

기본 요건

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

• 프로젝트 ID: Google Cloud 프로젝트 ID (GOOGLE_PROJECT_ID). 프로젝트에 탐색기 액세스, 기본 액세스 또는 일반 액세스 수준이 있는지 확인하려면 Google Ads API 개요 페이지를 확인하세요. 액세스 수준이 없는 경우 이러한 액세스 수준 중 하나를 신청합니다. 개발자 토큰 (GOOGLE_ADS_DEVELOPER_TOKEN)은 2026년 9월 9일에 지원이 종료되었으며 API 액세스 수준이 Google Cloud 프로젝트와 연결되어 있으므로 최신 버전의 Google Ads MCP 서버에서는 더 이상 필요하지 않습니다.
• OAuth 사용자 인증 정보: OAuth 2.0 클라이언트 ID/클라이언트 보안 비밀번호 쌍 또는 애플리케이션 기본 사용자 인증 정보 집합.

구성

서버를 MCP 호환 호스트에 통합하려면 settings.json과 같은 호스트의 MCP 구성 파일에 다음 항목을 추가하고 GOOGLE_APPLICATION_CREDENTIALS를 ADC JSON 파일로 가리키거나 gcloud auth application-default login으로 기본 ADC를 구성합니다. 관리자 계정을 통해 계정에 액세스하는 경우 GOOGLE_ADS_LOGIN_CUSTOMER_ID를 설정할 수도 있습니다. 이 구성의 정확한 위치와 파일 이름은 호스트의 문서를 참고하세요.

{
  "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_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

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: 애플리케이션 수준 OAuth 인증을 위한 OAuth 2.0 클라이언트 ID (Google Cloud 프로젝트에서 웹 애플리케이션 으로 구성됨)입니다. 다음 내용을 확인합니다.
  • 연결하려는 AI 클라이언트 (예: https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect 또는 https://antigravity.google/oauth-callback)에 적절한 승인된 리디렉션 URI를 추가했습니다.
  • API 및 서비스 > OAuth 동의 화면 > 데이터 액세스 (범위 추가 또는 삭제)의 OAuth 동의 화면에 https://www.googleapis.com/auth/adwords 범위를 추가했습니다.
  • OAuth 동의 화면 게시 상태가 테스트 (기본값)로 설정된 경우 서버에 연결하는 Google 계정을 테스트 사용자로 API 및 서비스 > OAuth 동의 화면 > 잠재고객 (테스트 사용자 > + 사용자 추가)에서 추가했습니다.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: OAuth 클라이언트 ID에 해당하는 OAuth 클라이언트 보안 비밀번호입니다.
• GOOGLE_ADS_MCP_BASE_URL: MCP 서버에 액세스할 수 있는 공개 기준 URL입니다 (예: https://google-ads-mcp-xyz-uc.a.run.app). Google Cloud Run은 초기 배포 중에 이 URL을 생성하므로 먼저 이 변수 없이 배포한 후 배포 후 서비스를 업데이트합니다.
• FASTMCP_HOST: FastMCP가 모든 IP 주소의 연결을 수락하도록 하려면 이 값을 0.0.0.0으로 설정합니다.

Google Cloud Run에 서비스를 배포합니다.

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,FASTMCP_HOST=0.0.0.0"

Cloud Run에서 배포를 완료한 후 할당된 서비스 URL을 검색하고 GOOGLE_ADS_MCP_BASE_URL 환경 변수로 서비스를 업데이트합니다.

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

인증 및 보안 모델

--allow-unauthenticated로 배포하면 외부 AI 클라이언트가 Google Cloud 서비스 계정 토큰 없이 연결할 수 있도록 Cloud Run의 인프라 수준 IAM 검사 (roles/run.invoker)가 사용 중지됩니다. 대신 인증이 애플리케이션 계층에 위임됩니다.

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID 및 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET이 제공되면 MCP 서버는 모든 수신 요청에 Google OAuth 2.0을 적용하여 인증되지 않은 호출자에게 HTTP 401 응답으로 문제를 제기합니다. 모든 도구 요청은 인증된 호출자의 OAuth ID에서만 엄격하게 실행됩니다.
• --allow-unauthenticated를 생략하면 호출자가 각 요청과 함께 Google Cloud OIDC ID 토큰을 전달해야 하는 Cloud Run 인프라 IAM이 적용됩니다. 표준 AI 클라이언트 (예: Claude 및 ChatGPT)는 Google Cloud IAM ID 토큰이 아닌 최종 사용자 OAuth를 사용하여 인증하므로 이러한 플랫폼에서 직접 연결하려면 애플리케이션 수준 OAuth가 포함된 --allow-unauthenticated가 필요합니다.

MCP 클라이언트 구성

배포 후 Cloud Run URL로 MCP 클라이언트를 구성합니다. 서버에는 OAuth 2.0 인증이 필요하므로 클라이언트는 MCP OAuth 흐름을 지원하거나 승인된 Bearer 토큰을 제공해야 합니다.

• OAuth 지원 클라이언트: MCP OAuth 검색을 지원하는 클라이언트(예: Antigravity)의 경우 엔드포인트에 연결하면 Google 계정으로 로그인하고 https://www.googleapis.com/auth/adwords 범위 (Google Cloud 콘솔에 .../auth/adwords로 표시됨)를 부여하는 인증 프롬프트가 트리거됩니다.
• 서드 파티 AI 플랫폼(Claude, ChatGPT): 클라이언트의 커넥터 또는 통합 설정에서 /mcp 경로가 있는 Cloud Run URL을 가리키는 커스텀 커넥터(예: https://your-cloud-run-url.a.run.app/mcp)를 추가하고 자체 OAuth 클라이언트 ID 및 클라이언트 보안 비밀번호를 사용하여 OAuth 2.0 인증을 선택한 후 클라이언트의 콜백 URI가 OAuth 클라이언트의 승인된 리디렉션 URI에 추가되었는지 확인합니다. 호스팅된 엔드포인트 파일럿의 허용 목록에 있는 참여자는 호스팅된 MCP 설정 가이드를 참고할 수도 있습니다.
• OAuth를 지원하지 않는 클라이언트: HTTP OAuth 흐름을 지원하지 않는 클라이언트는 HTTP 401 권한 없음 응답을 받습니다. 이러한 도구의 경우 로컬 stdio 구성을 대신 사용하세요.

OAuth 지원 클라이언트의 구성 예시 (예: ~/.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 리소스 유형(예: "campaign")에 관한 메타데이터를 검색합니다.

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

시작을 위한 샘플 프롬프트

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

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