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/SSE (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: 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 쿼리 언어 (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