google-ads-mcp

google-ads-mcp-unofficial

非官方的 Model Context Protocol 服务，让 AI Agent 能够读取、分析并（在受控条件下）操作 Google Ads 账户——暂停关键字、设置出价、调整预算，无需离开你的技术栈。

非官方，与 Google 没有关联。 这是一个本地优先的 MCP 服务，可直接调用 Google Ads REST API。它不包含超出 Google Ads API 允许范围的自动财务账户变更。启用 GOOGLE_ADS_ALLOW_MUTATIONS 前，请务必检查拟议的变更。

---

HTTP（v2 无状态）

默认使用 stdio。可选的 Streamable HTTP——无会话 ID，返回 JSON，仅限环回地址：

npx -y google-ads-mcp-unofficial --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

环境变量：GOOGLE_ADS_MCP_HOST、GOOGLE_ADS_MCP_PORT、GOOGLE_ADS_MCP_TRANSPORT=http。

快速开始（30 秒）

npx -y google-ads-mcp-unofficial setup

设置向导会收集你的开发者令牌和 OAuth 客户端信息，写入 ~/.google-ads-mcp/config.json（chmod 600），然后通过 http://127.0.0.1:3000/callback 上的本地回调，引导你完成 OAuth 流程。

验证：

npx -y google-ads-mcp-unofficial doctor

然后将其添加到你的 Agent 中（Claude Desktop、Cursor、Hermes、OpenClaw、Codex——示例见下文）。

---

功能

涵盖 6 个类别的 22 个工具。

类别	数量	示例
元数据 / 诊断	5	google_ads_connection_status、google_ads_capabilities、google_ads_agent_manifest、google_ads_data_inventory、google_ads_privacy_audit
共享 Delx 配置	3	google_ads_profile_get、google_ads_profile_update、google_ads_onboarding
身份验证	3	google_ads_get_auth_url、google_ads_exchange_code、google_ads_revoke_access
读取（始终安全）	8	google_ads_list_accounts、google_ads_list_campaigns、google_ads_get_campaign、google_ads_list_ad_groups、google_ads_list_keywords、google_ads_get_account_performance、google_ads_get_campaign_performance、google_ads_get_keyword_performance
工作流	2	google_ads_daily_report、google_ads_find_waste
变更操作（受控）	6	google_ads_pause_keyword、google_ads_resume_keyword、google_ads_set_keyword_bid_micros、google_ads_set_campaign_budget_micros、google_ads_pause_campaign、google_ads_resume_campaign

完整工具参考：参见 AGENTS.md。

---

设置向导

npx -y google-ads-mcp-unofficial setup [--allow-mutations] [--client hermes|claude|cursor|...]

向导会执行以下操作：

1. 提示输入：开发者令牌、OAuth 客户端 ID/密钥、可选的 login_customer_id（MCC）、重定向 URI、隐私模式。
2. 使用 chmod 600 写入 ~/.google-ads-mcp/config.json。
3. 写入 MCP 客户端配置（例如，在 macOS 上合并到 claude_desktop_config.json；使用 --client hermes 时写入 Hermes 配置块和技能文件）。
4. 打开 Google 的授权页面，并在 127.0.0.1:3000 监听，完成 OAuth 流程（除非使用 --no-auth）。

默认关闭变更操作。 --allow-mutations 会启用写入工具。启用前请先询问用户——这会允许 Agent 更改广告系列、出价和预算，以及暂停或恢复关键字。

---

认证模型

此 MCP 需要两项凭据：

1. Google Ads Developer Token — 从你的 MCC（经理）账号获取，网址为 https://ads.google.com/aw/apicenter。新令牌默认处于“测试账号访问”模式，生产流量需要先获得批准。
2. Google OAuth 2.0 Client — 在 Google Cloud Console 中创建的“桌面”或“Web”客户端。使用的唯一 OAuth 范围是 https://www.googleapis.com/auth/adwords。

⚠️ 刷新令牌注意事项： Google 只会在首次授权时，或你在 https://myaccount.google.com/permissions 撤销之前的授权后，返回 refresh_token。我们的 auth 流程会使用 prompt=consent，尽可能确保 Google 返回令牌；但如果代码交换响应中缺少 refresh_token，工具会提示你撤销授权后重试。

变量	用途	存储位置	是否为密钥？
GOOGLE_ADS_DEVELOPER_TOKEN	已获批准的开发者令牌	~/.google-ads-mcp/config.json 或环境变量	是
GOOGLE_ADS_CLIENT_ID	OAuth 客户端 ID	本地或环境变量	否
GOOGLE_ADS_CLIENT_SECRET	OAuth 客户端密钥	本地或环境变量	是
GOOGLE_ADS_LOGIN_CUSTOMER_ID	MCC ID（不带连字符）	本地或环境变量	否
GOOGLE_ADS_REDIRECT_URI	OAuth 回调	本地或环境变量（默认值为 http://127.0.0.1:3000/callback）	否
GOOGLE_ADS_PRIVACY_MODE	summary | structured | raw	本地或环境变量（默认值为 structured）	否
GOOGLE_ADS_ALLOW_MUTATIONS	启用写入工具	本地或环境变量（默认值为 false）	否
GOOGLE_ADS_TOKEN_PATH	覆盖令牌存储路径	本地或环境变量（默认值为 ~/.google-ads-mcp/tokens.json）	否
GOOGLE_ADS_CACHE	启用 SQLite 缓存	本地或环境变量（默认关闭）	否
GOOGLE_ADS_CACHE_PATH	覆盖缓存路径	本地或环境变量	否
GOOGLE_ADS_NO_RETRY	禁用重试中间件	环境变量（默认关闭）	否

---

隐私模式

模式	返回内容	客户 ID
summary	仅包含 ID、名称和状态字段	部分脱敏（123-***-7890）
structured（默认）	包含指标的扁平规范化行	部分脱敏
raw	完整的 Google Ads 上游 REST 负载	完整

每次调用时传入 privacy_mode，即可覆盖该响应的默认模式。

脱敏矩阵：

字段	summary	structured	raw
developer_token	不适用	不适用	不适用（绝不返回）
access_token、refresh_token、client_secret	所有错误中均为 [REDACTED]	[REDACTED]	[REDACTED]
错误消息中的电子邮件地址	[REDACTED]	[REDACTED]	[REDACTED]
customer_id	123-***-7890	123-***-7890	完整
指标（点击次数、费用等）	已删除	已包含	已包含

---

⚠️ 修改操作限制 — 请阅读

默认情况下，修改操作处于禁用状态。 以下六个工具受限制：

• google_ads_pause_keyword / google_ads_resume_keyword
• google_ads_set_keyword_bid_micros
• google_ads_set_campaign_budget_micros
• google_ads_pause_campaign / google_ads_resume_campaign

如果 Agent 未启用 GOOGLE_ADS_ALLOW_MUTATIONS 就调用其中任一工具，会得到：

Error: Write tools are disabled. To enable: re-run `google-ads-mcp-server setup --allow-mutations`
or enable GOOGLE_ADS_ALLOW_MUTATIONS. ASK THE USER BEFORE TURNING THIS ON — it lets agents
change campaigns, bids, budgets, and pause/resume keywords.

即使启用了环境变量，每次修改操作都必须在单次调用的参数中设置 explicit_user_intent: true。并且每次修改操作都会将资源名称记录到 stderr：

[google-ads-mcp] MUTATION pause_keyword {"resource_name":"customers/1234567890/adGroupCriteria/999~111222333"}

威胁模型请参阅 SECURITY.md。

---

Agent 客户端示例

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "google-ads-mcp-unofficial"]
    }
  }
}

然后重启 Claude Desktop。

Cursor / Windsurf

~/.cursor/mcp.json（或 IDE 中对应的配置文件）：

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Hermes

# ~/.hermes/config.yaml
mcp_servers:
  google-ads:
    command: npx
    args:
      - -y
      - [email protected]
    timeout: 120
    connect_timeout: 60
    sampling:
      enabled: false

然后运行 /reload-mcp（正常访问数据时不要重启网关）。

OpenClaw

~/.openclaw/mcp.servers.json：

{
  "google-ads": {
    "command": "npx",
    "args": ["-y", "[email protected]"]
  }
}

Codex / TOML 客户端

等效的 TOML 配置块请参阅 examples/codex.toml。

---

工作流示例

1. 每日效果概览

// Agent asks: "How did my Google Ads do yesterday?"
{
  "name": "google_ads_daily_report",
  "arguments": {
    "customer_id": "1234567890",
    "cpc_alert_threshold": 0.15
  }
}

返回包含昨天、7 天和 30 天汇总数据的 Markdown。如果昨天的 CPC 超过 0.15，输出中会显示 ALERT 横幅。

2. 识别浪费（只读）

{
  "name": "google_ads_find_waste",
  "arguments": {
    "customer_id": "1234567890",
    "date_range": "LAST_30_DAYS",
    "min_clicks": 5,
    "min_cost_micros": 200000,
    "zero_conversions_only": true
  }
}

返回与“花费 ≥ $0.20、点击 ≥5 次且转化次数为 0”匹配的关键词排名列表，但不会暂停它们。

3. 暂停单个关键词（有门控的变更）

用户确认后：

{
  "name": "google_ads_pause_keyword",
  "arguments": {
    "customer_id": "1234567890",
    "ad_group_id": "999",
    "criterion_id": "111222333",
    "explicit_user_intent": true
  }
}

---

故障排查

症状	操作
Missing required Google Ads environment variables	运行 setup，或设置错误中列出的环境变量。
Google did not return a refresh_token	前往 https://myaccount.google.com/permissions 撤销授权，然后重新运行 auth。
读取时出现 PERMISSION_DENIED	确认 GOOGLE_ADS_LOGIN_CUSTOMER_ID 与拥有目标客户的 MCC 匹配（不含连字符）。
Write tools are disabled	这是预期行为。启用 GOOGLE_ADS_ALLOW_MUTATIONS 前，请先征得用户同意。
编辑配置后 Hermes 工具缺失	运行 /reload-mcp 或 hermes mcp test google-ads。请勿重启网关。
Token 文件权限不安全警告	chmod 600 ~/.google-ads-mcp/tokens.json

---

支持

• GitHub Issues：https://github.com/davidmosiah/google-ads-mcp-unofficial/issues
• 电子邮件：[email protected]
• X：@delx369

---

免责声明

非官方集成。与 Google 无关联。 除 Google Ads REST API 允许的操作外，此 MCP 不包含自动更改财务账户的功能。启用 GOOGLE_ADS_ALLOW_MUTATIONS 前，请务必检查拟议的更改。对于预算超支、广告系列暂停，或自动更改 Google Ads 账户带来的任何其他后果，作者概不负责。

基于 MIT 许可证授权。

Skill 或 MCP

同一软件包，两种使用方式。MCP 通过 stdio/HTTP 注册工具。当客户端没有 MCP 时，skill 可以通过 CLI 调用相同的工具：

npx -y google-ads-mcp-unofficial call google_ads_connection_status --json '{}'

将 skill/SKILL.md 复制到你的 Agent 技能目录。