google-ads-mcp

Google Ads API용 읽기 전용 MCP 서버입니다. 리포트 관련 도구(페이너, 광고그룹, 키워드, 원시GAQL 리)를 제공하여 MCP 클라이언트 (클라이드 Code, Claude Desktop 등)가 Google Ads 계정을 조회할 수 있습니다. 변경/쓰기 도구는 없습니다 — 이 서버는 캠페인너, 예산, 입찰가량을 변경할 수 없습니다.

도구

사전 준비 사항

Google Ads API 자격증명이 필요합니다:

1. 개발자 토큰 를발 — 인증에 사용할 관리자 계정의 Google Ads API 어국 (Tools & Settings을 → API)에서 발버받은 토큰.

2. OAuth2 클라이언트 ID / 클라이언트 시크릿 — Google Ads ** API가 사용 가능한 Google Cloud 프로젝트에서 발버받습니다.

3. 리프레시 토큰 — 대상 계정(들)에 접근할 수 있는 사용자의 토큰. Google의 OAuth 데스크톰 플로우 가이드를 참조하거나, 구 Jupiter (predicategoogle-ads의 파이든 라이브러리와 함께 제공되는 헬퍼 스크립트를 실행하세요.

4. 클라이언트 계정을 대신하여 관리자(MCC) 계정으로 인증하는 경우, 그 계정의 login_customer_id.

설정

# from the repo root
pip install -e .

자격증명은 다음 두 가지 방법으로 구성할 수 있습니다:

옵션 A: YAML 파일

cp google-ads.yaml.example google-ads.yaml
# edit google-ads.yaml with your values

옵션 B: 환경 변수

cp .env.example .env
# edit .env, then export the variables into your shell environment

현재 디렉터리의 google-ads.yaml 또는 GOOGLE_ADS_* 환경변수는 자동으로 감지됩니다. SM**GOOGLE_ADS_CONFIGURATION_FILE_PATH를 설정**하여 다른 위치에 있는 YAML 파일을 지정할 수도 있습니다.

단독 실수

python -m google_ads_mcp
# or, after `pip install -e .`:
google-ads-mcp

이 서버는 MCP 명세에 따라 stdio를통해 통신합니다.

MCP 클라이언트 등록

Claude Code (프로젝트 수준의 .mcp.json, 또는 claude mcp add):

{
  "mcpServers": {
    "google-ads": {
      "command": "google-ads-mcp",
      "env": {
        "GOOGLE_ADS_CONFIGURATION_FILE_PATH": "/absolute/path/to/google-ads.yaml"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json): 상기와 동일한 mcpServers 항목을 사용하게 됩니다.

보안 참고 사항

• 이 서버는 GoogleAds.earchStream을 통해서만 GAQL SELECT리를 실행합니다. GAQL에는INSERT/UPDATE/DELETE` 문법이 없으므로, 이 도구들로 Google Ads 데이터를 변경할 수 없습니다.

• google-ads.yaml 또는 .env는 커밋하지 마세요 — 두 파일 모두 gitignored 입니다. 개발자 토큰, OAuth 클라이언트 시크릿, 리프레시 토큰은 자격증명으로 취급합니다.

• customer_id 및 엔티티 ID는 GAQL 쿼리 문자열에 삽입되기 전에 숫자로 검증됩니다.