Google Ads MCP

Google Ads MCP

Google Ads API 的只读 MCP 服务。11 个工具涵盖发现、GAQL 报告、资源架构、建议、关键词规划与预测，以及对管理账号（MCC）下任何可访问账号的更改历史。我们在生产环境中为所有广告客户运行此服务。通过三个层级强制只读：不导入修改或应用服务、SDK 方法允许列表，以及要求 GAQL 以 SELECT 开头的检查。

安装

Claude Code：

claude mcp add google-ads \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CLIENT_ID=your-client-id \
  -e GOOGLE_ADS_CLIENT_SECRET=your-client-secret \
  -e GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token \
  -e GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \
  -- uvx scalably-google-ads-mcp

Codex：

codex mcp add google-ads \
  --env GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  --env GOOGLE_ADS_CLIENT_ID=your-client-id \
  --env GOOGLE_ADS_CLIENT_SECRET=your-client-secret \
  --env GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token \
  --env GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 \
  -- uvx scalably-google-ads-mcp

Claude Desktop：从最新的 GitHub 版本下载 google-ads-mcp.mcpb 并打开。

设置

这是工具库中设置最繁重的一项：等待开发者令牌审批最长可能需要两天。一组以管理账号（MCC）为根的凭据，可以读取其关联的任何客户账号，因此除了将账号关联到 MCC 之外，无需为每个客户单独配置。

1. Google Ads 开发者令牌。 使用管理账号登录 ads.google.com，前往“工具和设置”中的“API 中心”，申请开发者令牌。新令牌的访问级别为 Explorer；Google 审核后会授予此级别，审核可能需要几天。在此级别可使用发现、查询和建议工具。更高配额需要 Basic 访问权限（需单独申请），关键词规划工具也可能需要此权限。
2. Google Cloud OAuth 客户端。 在 Google Cloud 项目中启用 Google Ads API，然后在“API 和服务”中的“凭据”下创建类型为 Desktop app 的 OAuth 客户端 ID。记下客户端 ID 和客户端密钥，并将 https://www.googleapis.com/auth/adwords 范围添加到 OAuth 同意屏幕。
3. 刷新令牌。 使用管理账号的管理员用户，通过 Google 的 oauth2l 工具或 google-ads Python 库附带的 generate_user_credentials.py 示例，生成一次刷新令牌。保存刷新令牌；正常使用时它不会过期。
4. 登录客户 ID。 将管理账号本身的 10 位客户 ID（不带连字符）用作 GOOGLE_ADS_LOGIN_CUSTOMER_ID。任何客户账号都可以在自己的 Google Ads 界面中接受邀请，以关联到此管理账号；关联后，google_ads_list_customer_clients 即可找到该账号。

工具（11 个）

工具	功能
google_ads_list_accessible_customers	列出 OAuth 用户可直接访问的所有 customer_id
google_ads_list_customer_clients	遍历 MCC 层级并返回所有子账号
google_ads_query	对指定客户账号运行 GAQL 查询
google_ads_describe_resource	查询 GAQL 资源的架构（字段、指标、细分）
google_ads_list_resources	返回完整的 GAQL 资源目录
google_ads_recommendations	读取 Google 针对客户账号的优化建议
google_ads_keyword_ideas	生成关键词建议，并提供搜索量、竞争程度和 CPC 估算值
google_ads_keyword_historical_metrics	查询指定关键词的历史月度搜索量和竞争程度指标
google_ads_keyword_forecast_metrics	预测拟定关键词计划的 KPI
google_ads_change_events	审计记录：近 30 天内谁更改了什么
google_ads_change_status	按资源跟踪轻量级的最后修改记录

配置

变量	必填	用途
GOOGLE_ADS_DEVELOPER_TOKEN	是	来自 Ads API Center 的 Google Ads API 开发者令牌
GOOGLE_ADS_CLIENT_ID	是	桌面应用凭据的 OAuth2 client_id
GOOGLE_ADS_CLIENT_SECRET	是	与 client_id 配对的 OAuth2 client_secret
GOOGLE_ADS_REFRESH_TOKEN	是	用于 adwords 范围的长期有效 OAuth2 refresh_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID	是	管理员账号（MCC）的 10 位客户 ID，不带连字符
GOOGLE_ADS_API_VERSION	否	要使用的 Google Ads API 版本，默认为 v25
GOOGLE_ADS_USE_PROTO_PLUS	否	使用 proto-plus 消息类型，默认为 true
GOOGLE_ADS_LOG_LEVEL	否	Python 日志级别，默认为 WARNING

返回结构

每个工具都会返回包含 status（succeeded、partial、no_op）、operation、summary、target、result、proof、warnings 和 recovery 的 JSON。失败时会返回工具错误，文本为 google_ads_request_failed: <message> <hint>。proof.apiVersion 指明所用的 Google Ads API 版本。google_ads_query 会设置 proof.microsConverted。partial 状态表示结果达到配置的上限（max_rows、page_size 或 limit）；recovery.nextAction 会说明如何继续。

限制

Google Ads API 将 google_ads_query 每次调用的响应大小限制为 64 MB；处理较大的日期范围时，请拆分为多次调用。KeywordPlanIdeaService（关键字创意、历史指标、预测）的速率限制为每秒 1 次查询；如果在 Explorer 层级遇到权限错误，可能需要 Basic Access。google_ads_change_events 最多涵盖过去 30 天；google_ads_change_status 最多涵盖过去 14 天。metrics.cost_micros 及其他 *_micros 字段中，1 单位 = $0.000001；当 convert_micros 为 true（默认值）时，google_ads_query 会同时输出对应的 *_units 字段。

验证

每个版本都会在 CHANGELOG.md 中列出软件包版本、.mcpb 的 sha256，以及该版本所基于的生产提交。每次推送时，CI 都会运行测试，并对构建的 wheel 执行全新安装。

隐私政策

此服务在你的设备上本地运行，使用你自己的凭据。它不会收集个人数据，不包含遥测功能，不会持久化存储任何内容，并且只会与其封装的供应商 API 通信。包括 Scalably 在内的任何第三方都不会收到你的数据。联系邮箱：[email protected]。规范版本：https://scalably.io/connector-privacy.html

许可证

MIT。版权归 Scalably 所有。