Google Ads MCP

Google Ads MCP는 Google Ads 계정을 검사하기 위한 로컬, 보안 우선, 읽기 전용 MCP 서버 및 Codex 플러그인입니다. 버전 0.1.0은 제한된 인벤토리, 보고, 메타데이터, 변경 내역 및 안전한 GAQL 도구를 제공합니다. 쓰기, 업로드, 일정 예약, 삭제, 최적화 또는 호스팅 전송 기능은 포함하지 않습니다.

공개 Python 배포판의 이름은 google-ads-operator-mcp입니다. 제품 및 명령은 계속 Google Ads MCP 및 google-ads-mcp입니다.

보안 경계

• 모든 계정 범위 요청은 프로필과 고객 ID를 함께 지정합니다.

• Google 자격 증명은 Application Default Credentials 또는 리포지토리 외부의 명시적 소유자 전용 google-ads.yaml에 유지됩니다.

• accounts.json에는 개발자 토큰에 대한 환경 변수 이름만 포함될 수 있으며 토큰 자체는 절대 포함될 수 없습니다.

• allowWrites는 false여야 하며, 다른 값은 거부됩니다.

• 프로덕션 어댑터는 GoogleAdsService, CustomerService 및 GoogleAdsFieldService만 생성합니다.

• 도구는 정규화된 행을 받으며 Google 클라이언트 또는 원시 응답 봉투를 받지 않습니다.

• MCP 모드는 JSON-RPC용으로 stdout을 예약합니다. 진단 및 정화된 오류 코드는 stderr로 전송됩니다.

프로덕션 계정을 연결하기 전에 SECURITY.md, PRIVACY.md 및 위협 모델을 읽으십시오.

Related MCP server: appstoreconnect-codex-mcp

요구 사항

• Python 3.11, 3.12 또는 3.13

• uv

• 개발자 토큰이 있는 Google Ads API 액세스

• ADC 또는 별도로 저장된 소유자 전용 google-ads.yaml

개발자 토큰, Python 클라이언트 구성 및 Application Default Credentials에 대한 Google 공식 지침을 사용하십시오.

로컬 설정

uv sync --frozen --all-groups
uv run --frozen google-ads-mcp version
uv run --frozen google-ads-mcp config init

공개 릴리스 이후에는 독립 실행형 CLI를 uv tool install google-ads-operator-mcp==0.1.0으로 설치할 수도 있습니다. 최종 클린 플러그인 승인 게이트에는 소스 트리 사본이 아닌 릴리스 플러그인 아카이브를 사용하십시오.

~/.config/google-ads-mcp/accounts.json을 편집하고 공개 계정 ID를 교체한 다음 소유자 전용 권한을 복원하십시오:

GOOGLE_ADS_DEVELOPER_TOKEN을 저장소나 셸 기록에 값을 넣지 않고 로컬 비밀 관리자에서 노출한 다음 실행하십시오:

chmod 600 ~/.config/google-ads-mcp/accounts.json
gcloud auth application-default login
uv run --frozen google-ads-mcp config validate
uv run --frozen google-ads-mcp auth doctor --profile production-read-only

개발자 토큰, OAuth 갱신 토큰, 클라이언트 시크릿, ADC JSON 또는 YAML 내용을 이 저장소, 이슈, 터미널 기록 또는 채팅에 붙여넣지 마십시오.

구성

구성 우선 순위는 --config, 그 다음 GOOGLE_ADS_MCP_CONFIG, 그 다음 ~/.config/google-ads-mcp/accounts.json입니다.

{
  "profiles": [
    {
      "name": "production-read-only",
      "loginCustomerId": "1234567890",
      "defaultCustomerId": "0987654321",
      "auth": {
        "type": "adc",
        "developerTokenEnv": "GOOGLE_ADS_DEVELOPER_TOKEN"
      },
      "allowWrites": false
    }
  ]
}

기존 Google 클라이언트 YAML의 경우 {"type":"googleAdsYaml","path":"/absolute/owner-only/google-ads.yaml"}을 사용하십시오. 상대 경로와 심볼릭 링크는 거부됩니다. 서버는 YAML 자격 증명을 위해 작업 디렉터리나 저장소를 검색하지 않습니다.

CLI

google-ads-mcp version
google-ads-mcp config init
google-ads-mcp config validate
google-ads-mcp auth doctor --profile <name>
google-ads-mcp accounts discover --profile <name>
google-ads-mcp serve --stdio

MCP 도구

v0.1의 고정된 도구 표면은 다음과 같습니다:

auth_check                customers_list
customer_get              customer_hierarchy
account_health            campaigns_query
campaign_inventory        resource_metadata
reports_catalog           report_run
change_events_query       gaql_validate
gaql_search

유형화된 목록은 페이지당 최대 200개 항목을 반환합니다. 단일 Google 읽기는 정규화된 행 1,000개로 제한됩니다. 5분 커서는 프로필과 정확한 요청에 바인딩되며 프로필당 활성 커서는 최대 20개입니다. 안전한 GAQL에는 커서가 없으며 주석이 없는 단일 SELECT, 민감하지 않은 리소스 및 LIMIT 1..1000이 필요합니다.

매개변수, 증거 의미 및 리포트 동작은 docs/tools.md를 참조하십시오.

Codex 플러그인

저장소 루트가 플러그인 루트입니다. .mcp.json은 ./bin/google-ads-mcp-launcher를 호출하며, 이는 stdio를 통해 고정된 uv 환경만 실행합니다. 암시적 google-ads-operator 스킬은 모든 계정 문자열을 신뢰할 수 없는 데이터로 취급하며 사용할 수 없는 변경 도구를 제안하지 않습니다.

저장소는 의도적으로 개인 마켓플레이스 항목을 생성하거나 수정하지 않습니다. 릴리스 아카이브 설치는 승인 중에 별도로 검증됩니다.

검증

uv run --frozen ruff check .
uv run --frozen pyright
uv run --frozen pytest
uv run --frozen python scripts/validate_read_only.py
uv run --frozen python scripts/validate_gaql_templates.py
uv run --frozen python ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
uv run --frozen python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/google-ads-operator

자동화된 검증은 실계정 승인이 아닙니다. docs/acceptance.md의 테스트 계정 및 프로덕션 읽기 전용 게이트는 v0.1.0 이전에 계속 필요합니다.

라이선스

Apache-2.0. Google Ads는 Google LLC의 상표입니다. 이 프로젝트는 독립적이며 Google의 보증을 받지 않습니다.