google-ads-manager-mcp

Google Ads Manager MCP

非官方社区维护项目。与 Google 无关，也未获 Google 认可或赞助。 “Google Ads” 是 Google LLC 的商标。

一个本地 MCP（Model Context Protocol）服务，让 AI 助手能够读取和管理 Google Ads 账户：运行 GAQL 报告、创建广告系列、暂停／启用广告系列，以及添加关键词。

Google 也发布了官方 Google Ads MCP 服务，该服务为只读（仅用于报告／诊断）。本项目涵盖相同的报告功能，并增加了写入支持——创建和编辑广告系列、预算、广告组、关键词和广告——且通过草稿／确认安全层进行限制，避免账户意外发生更改。

所有写入操作都必须通过草稿 → 确认安全流程：用于“创建”或“更新”内容的工具只会使用 Google API（validate_only）验证更改，并返回带有预览的 draftId。在你使用该 draftId 调用 confirm_write 之前，Ads 账户不会发生任何更改。草稿会在 10 分钟后过期。

工具

只读：

• list_accessible_customers — 查看此刷新令牌可以访问哪些账户
• search_gaql — 运行任意原始 GAQL SELECT 查询
• get_campaigns — 获取包含状态、预算和核心指标的广告系列
• get_ad_groups — 获取广告组（可选择按广告系列筛选）及其指标
• get_keywords — 获取包含匹配类型、状态和指标的关键词条件
• get_search_terms — 查看触发广告的实际搜索词，以便寻找否定关键词候选项

写入（草稿 → 确认）：

• create_campaign — 创建新的广告系列和预算；除非另有说明，否则创建后为 PAUSED
• update_campaign_status — 启用／暂停／移除广告系列
• update_campaign_budget — 更改现有广告系列的每日预算
• add_keywords — 向广告组添加关键词条件
• create_ad_group — 在现有广告系列中创建新广告组
• update_ad_group_status — 启用／暂停／移除广告组
• update_keyword_status — 启用／暂停／移除关键词条件
• add_negative_keywords — 向广告组添加否定关键词条件
• create_responsive_search_ad — 创建新的响应式搜索广告；除非另有说明，否则创建后为 PAUSED
• confirm_write — 真正执行之前返回的 draftId

设置

1. Google Ads 开发者令牌

Google Ads → 工具和设置 → API Center。测试账户令牌会立即发放；生产级令牌需要 Google 人工审核（约 1-2 周），因此如果你打算将其用于测试账户以外的用途，请尽早申请。

2. OAuth 客户端

Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID。 选择应用类型 Desktop app。复制客户端 ID 和客户端密钥。

3. 配置环境

cp .env.example .env

填写 GOOGLE_ADS_CLIENT_ID、GOOGLE_ADS_CLIENT_SECRET、GOOGLE_ADS_DEVELOPER_TOKEN 和 GOOGLE_ADS_CUSTOMER_ID（此服务要管理的账户 ID，包含 10 位数字，可选使用连字符）。如果 该账户是管理账号（MCC）下的客户账户，还需将 GOOGLE_ADS_LOGIN_CUSTOMER_ID 设置为 管理账号的 ID。

4. 获取刷新令牌

npm install
npm run auth

这会打开授权 URL——打开该链接，使用有权访问你的 Ads 账户的 Google 账号登录，并批准 adwords 范围。脚本会输出 GOOGLE_ADS_REFRESH_TOKEN； 将其添加到 .env。

5. 构建

npm run build

6. 将 MCP 客户端指向此服务

对于 Claude Desktop / Claude Code，将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "google-ads-manager": {
      "command": "node",
      "args": ["/absolute/path/to/google ads manger mcp/build/index.js"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "..."
      }
    }
  }
}

（或者跳过 env 代码块，只需确保 .env 已填好——直接运行时，服务会通过 dotenv 加载该文件，例如在本地迭代时运行 npm run dev。）

备注

• 此工具仅适用于单个 Google Ads 账户（GOOGLE_ADS_CUSTOMER_ID）。如需在一个经理账户下管理多个客户账户，可以为每个客户 ID 分别运行一个实例，或扩展 googleAdsClient.ts，让每次工具调用都能传入一个 customerId 参数。
• 新建广告系列默认处于 PAUSED 状态（startEnabled: false），因此除非你明确启用，否则不会产生费用。

贡献

欢迎提交问题和 PR — 最有价值的后续改进包括新增报告类型、支持在广告系列级别设置否定关键字，以及支持多账户（MCC）管理。

许可证

MIT