Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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

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

커뮤니티 리소스 및 지원

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 또는 서비스 계정

상호작용 루프 작동 방식

요청: 사용자가 "이번 주 캠페인 실적은 어때?"와 같은 질문을 제출합니다.
탐색: LLM은 사용 가능한 도구를 검사하고 google-ads-mcp 검색 기능을 식별합니다.
실행: MCP 서버가 기본 Python 로직을 실행하여 Google Ads API를 쿼리합니다.
컨텍스트 삽입: 구조화된 결과가 LLM의 컨텍스트 창으로 반환됩니다.
대답: 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 호환 호스트에 통합하려면 호스트의 MCP 구성 파일(예: settings.json)에 다음 항목을 추가하고 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 Ads MCP 서버는 AI 클라이언트에 실시간 계정 데이터에 대한 읽기 전용 액세스 권한을 부여합니다. 에이전트가 유효한 Google Ads Query Language(GAQL) 쿼리를 구성하고, 계정 실적 변화를 진단하고, 클라이언트 라이브러리 코드를 생성할 수 있도록 MCP 서버를 다음 도우미 도구와 페어링하세요.

Google Ads API 에이전트 기술: google-ads-api-mcp-setup, google-ads-api-account-diagnostics, google-ads-api-quickstart를 비롯한 Google Ads API 관련 안내 및 워크플로의 이식 가능한 모듈로, 에이전트가 더 낮은 토큰 오버헤드로 Google Ads MCP 서버를 효과적으로 사용하는 방법을 알려줍니다. 단일 명령어로 설치하거나 (Node.js 필요) Antigravity, Claude Code, Codex, Cursor 옵션에 관한 Google Ads API 에이전트 기술 가이드를 참고하세요.
```
npx skills add google/skills/skills/ads
```
Google Ads API 개발자 어시스턴트: 로컬 Protobuf 스키마 검사, 프로그래매틱 GAQL 검증, 클라이언트 라이브러리 코드 생성 (변형 스크립트 포함), 오프라인 전환 문제 해결을 제공하는 Google Antigravity 및 Claude Code용 모듈식 플러그인입니다. Google Ads API 개발자 어시스턴트란 무엇인가요?에서 작동 방식을 알아보거나 설치 가이드를 따르세요.

Google Cloud에 배포

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

기본 요건

Google Cloud 프로젝트
gcloud 명령줄 도구가 설치 및 인증되고 활성 프로젝트가 구성되어 있어야 합니다.
```
gcloud config set project YOUR_PROJECT_ID
```

Docker 이미지 빌드 및 푸시

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

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

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

프로젝트 디렉터리로 이동합니다.
```
cd <full path>/google-ads-mcp
```
이미지를 빌드하고 제출합니다.
```
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 동의 화면 게시 상태가 테스트(기본값)로 설정된 경우 MCP 서버에 연결하는 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로 배포하면 Cloud Run의 인프라 수준 IAM 검사 (roles/run.invoker)가 사용 중지되므로 외부 AI 클라이언트가 Google Cloud 서비스 계정 토큰 없이 연결할 수 있습니다. 대신 인증이 애플리케이션 계층에 위임됩니다.

GOOGLE_ADS_MCP_OAUTH_CLIENT_ID 및 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET가 제공되면 MCP 서버는 모든 수신 요청에 Google OAuth 2.0을 적용하여 인증되지 않은 호출자에게 HTTP 401 응답을 반환합니다. 모든 도구 요청은 인증된 호출자의 OAuth ID로 엄격하게 실행됩니다.
--allow-unauthenticated를 생략하면 Cloud Run 인프라 IAM이 적용되므로 호출자가 각 요청과 함께 Google Cloud OIDC ID 토큰을 전달해야 합니다. 표준 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 2.0 인증을 선택하고(자체 OAuth 클라이언트 ID 및 클라이언트 보안 비밀번호 사용), 클라이언트의 콜백 URI가 OAuth 클라이언트의 승인된 리디렉션 URI에 추가되었는지 확인합니다. (호스팅된 엔드포인트 파일럿의 허용 목록에 추가된 참여자는 호스팅된 MCP 설정 가이드를 참조할 수도 있습니다.)
OAuth 지원이 없는 클라이언트: HTTP OAuth 흐름을 지원하지 않는 클라이언트는 HTTP 401 Unauthorized 응답을 수신합니다. 이러한 도구의 경우 로컬 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: 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

Google Ads MCP 서버: 개발자 통합 가이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

커뮤니티 리소스 및 지원

기술 개요

주요 사양

상호작용 루프 작동 방식

시작하기

기본 요건

구성

선택사항: 에이전트에 스킬 및 개발자 어시스턴트 추가

Google Cloud에 배포

기본 요건

Docker 이미지 빌드 및 푸시

Google Cloud Run에 배포

인증 및 보안 모델

MCP 클라이언트 구성

핵심 기능 (도구)

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

다음 단계

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