google-ads

MCP Google Ads Server

一个适用于 Google Ads API 的 MCP（Model Context Protocol）服务，内置保障机制，可在更改正式生效前进行审核。已在生产环境中验证，支持 MCC（经理账号），提供 36 个用于广告系列管理、报告和优化的工具。v1.2.0 新增端到端的 Demand Gen 广告系列创建功能。

功能

• MCC 支持：适用于经理账号和多个客户账号
• 自动上下文：根据你的工作目录检测对应的客户账号
• 默认安全：所有新建项目均处于 PAUSED 状态
• 审批工作流：仅在人工审核后启用项目
• 验证：创建广告前先进行验证，以便尽早发现错误
• 韧性：断路器、带退避的重试和超时处理（cockatiel）
• 结构化日志记录：基于 Pino 的日志记录，带构建指纹

设置

1. Google Ads API 访问权限

你需要：

• Google Ads 开发者令牌（在 Google Ads API Center 申请）
• OAuth 凭据（来自 Google Cloud Console 的客户端 ID 和密钥）
• MCC 账号的刷新令牌

获取 OAuth 凭据

1. 前往 Google Cloud Console
2. 创建项目或选择现有项目
3. 启用 Google Ads API
4. 前往 凭据 → 创建凭据 → OAuth 客户端 ID
5. 选择 桌面应用
6. 下载 JSON 文件（包含 client_id 和 client_secret）

获取刷新令牌

使用你自己的 OAuth 客户端（上一步中的 client_id / client_secret），并运行随附的辅助程序。它会通过 PKCE (S256) 执行 Google 的已安装应用环回流程，并输出刷新令牌。它不会读取主目录中的任何内容，也不需要共享的 OAuth 密钥文件。

export GOOGLE_ADS_CLIENT_ID="YOUR_CLIENT_ID.apps.googleusercontent.com"
export GOOGLE_ADS_CLIENT_SECRET="YOUR_CLIENT_SECRET"
node get-refresh-token.cjs

浏览器会打开 Google 登录页面；请使用拥有 Ads 数据的 Google 账号登录并授权。成功后，辅助程序会向 stdout 输出一行内容：

GOOGLE_ADS_REFRESH_TOKEN=1//0a...

将该值设为环境变量（或写入下方的 config.json）。请求的 OAuth 范围从 config.json（oauth.scope）读取；如果没有，则回退到 config.example.json，因此辅助程序和运行中的服务始终会请求相同的范围。此 MCP 仅请求所需的最小范围： https://www.googleapis.com/auth/adwords。

请勿将其运行时的 stdout 重定向到共享日志文件——刷新令牌会按设计输出到 stdout。

注意：GOOGLE_ADS_DEVELOPER_TOKEN 是单独的 Google Ads API 凭据，并非 OAuth 范围——请单独设置（见下方的环境变量）。

2. 安装

npm install mcp-google-ads

或者克隆并从源代码构建：

git clone https://github.com/mharnett/mcp-google-ads.git
cd mcp-google-ads
npm install
npm run build

**安全：**切勿分享 .mcp.json 文件，也不要将其提交到 git——其中可能包含 API 凭据。请将 .mcp.json 添加到 .gitignore。

3. 配置

cp config.example.json config.json

使用你的凭据编辑 config.json：

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/adwords"
  },
  "google_ads": {
    "developer_token": "YOUR_DEVELOPER_TOKEN",
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "mcc_customer_id": "123-456-7890"
  },
  "clients": {
    "my-client": {
      "customer_id": "111-222-3333",
      "name": "My Client",
      "folder": "/path/to/client/workspace"
    },
    "another-client": {
      "customer_id": "444-555-6666",
      "name": "Another Client",
      "folder": "/path/to/another/workspace"
    }
  },
  "defaults": {
    "create_paused": true,
    "label_prefix": "claude-",
    "require_approval_for_enable": true
  }
}

环境变量

也可以通过环境变量设置凭据（这些变量会覆盖 config.json 中的设置）：

变量	必需	说明
GOOGLE_ADS_DEVELOPER_TOKEN	是	Google Ads API 开发者令牌
GOOGLE_ADS_CLIENT_ID	是	OAuth 2.0 客户端 ID
GOOGLE_ADS_CLIENT_SECRET	是	OAuth 2.0 客户端密钥
GOOGLE_ADS_REFRESH_TOKEN	是	OAuth 2.0 刷新令牌
GOOGLE_ADS_MCP_WRITE	否	设为 true 以提供变更类工具（创建/更新/暂停/启用/移除/应用）。默认：只读。
GOOGLE_ADS_MCP_ALWAYS_LOAD	否	以逗号分隔的工具名称列表，将这些工具标记为始终加载，例如 google_ads_get_client_context,google_ads_gaql_query。默认：未设置（不标记任何工具）。

始终加载的工具

对于将工具架构延迟到工具搜索步骤后才加载的客户端，只有在搜索某个工具后才会加载该工具。在 GOOGLE_ADS_MCP_ALWAYS_LOAD 中指定工具名称，会在 tools/list 中为这些工具添加 _meta: {"anthropic/alwaysLoad": true}，以便直接提供这些工具。与任何工具都不匹配的名称会被忽略，而且此标记绝不会让只读模式隐藏的工具变为可用。

默认只读

服务默认以只读模式运行。在 MCP 服务环境中设置 GOOGLE_ADS_MCP_WRITE=true 之前，变更类工具（任何用于创建、更新、暂停、启用、移除、关联或应用的工具）都会从工具列表中隐藏。 如果未设置该标志却调用了写入工具，服务会返回明确错误，并指出相关环境变量。

这是刻意设计的：像“启用筹款广告系列”这样的随意聊天消息，不应在未经明确选择的情况下改变投放中的广告支出。

4. 添加到 Claude Code

将以下内容添加到 Claude Code MCP 设置中（~/.claude/settings.json 或项目设置）：

{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["node_modules/mcp-google-ads/dist/index.js"]
    }
  }
}

或者，如果从源码安装：

{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["/path/to/mcp-google-ads/dist/index.js"]
    }
  }
}

重启 Claude Code。

**Claude Desktop：**将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

使用方法

工作流

1. cd into client folder → auto-detects account context
2. Ask Claude to create campaigns/ads → all created PAUSED
3. Review in Google Ads UI or Editor
4. Tell Claude to enable approved items
5. Claude enables (requires your approval prompt)

可用工具（36 个）

上下文与发现

工具	说明
google_ads_get_client_context	根据工作目录检测所属账号
google_ads_list_campaigns	列出所有广告系列及其状态和指标
google_ads_list_ad_groups	列出某个广告系列中的广告组
google_ads_list_pending_changes	显示带有 claude- 标签的已暂停项目
google_ads_list_conversion_actions	列出转化操作

广告系列管理

工具	说明
google_ads_create_campaign	创建广告系列（PAUSED）。支持 SEARCH + DEMAND_GEN 渠道、更丰富的出价方式（MANUAL_CPC / MAXIMIZE_CLICKS / MAXIMIZE_CONVERSIONS / TARGET_CPA）、地理位置和语言定位，以及开始和结束日期
google_ads_create_ad_group	创建广告组（PAUSED）。type 接受 SEARCH_STANDARD（默认）或 DEMAND_GEN_MULTI_ASSET_AD_GROUP
google_ads_create_responsive_search_ad	创建经过验证的 RSA（PAUSED）
google_ads_create_image_asset	上传 PNG/JPG/GIF 图片素材（验证文件大小 ≤5MB、尺寸 ≥600×314），用于 Demand Gen 广告
google_ads_create_demand_gen_multi_asset_ad	创建 Demand Gen 多素材广告（PAUSED）——在调用 API 前验证字符数和数量上限；如果 ad_group 不是 DG，则快速失败
google_ads_create_keywords	创建关键字（PAUSED）
google_ads_validate_ad	验证 RSA，但不创建
google_ads_enable_items	启用项目（使其变为 LIVE）——需要审批
google_ads_pause_items	暂停已启用的项目
google_ads_pause_keywords	暂停指定关键字
google_ads_update_campaign_budget	更新广告系列每日预算

跟踪与 URL

工具	说明
google_ads_get_campaign_tracking	获取跟踪模板和 URL 参数
google_ads_update_campaign_tracking	更新跟踪模板

否定关键字

工具	说明
google_ads_create_shared_set	创建共享否定关键字列表
google_ads_link_shared_set	将共享集合关联到广告系列
google_ads_unlink_shared_set	取消共享集合与广告系列的关联
google_ads_add_shared_negatives	将关键字添加到共享否定列表
google_ads_remove_shared_negatives	从共享列表中移除关键字
google_ads_add_campaign_negatives	添加广告系列级否定关键字
google_ads_remove_campaign_negatives	移除广告系列级否定关键字
google_ads_remove_adgroup_negatives	移除广告组级否定关键字

效果与报告

工具	描述
google_ads_keyword_performance	包含质量得分的关键词指标
google_ads_keyword_performance_by_conversion	按转化操作划分的关键词指标
google_ads_ad_performance	广告级效果指标
google_ads_ad_performance_by_conversion	按转化操作划分的广告指标
google_ads_search_term_report	搜索词查询报告
google_ads_search_term_report_by_conversion	按转化操作划分的搜索词
google_ads_search_term_insights	搜索词类别洞察
google_ads_search_term_insight_terms	洞察类别中的搜索词
google_ads_keyword_volume	关键词规划师的搜索量估算

高级功能

工具	描述
google_ads_gaql_query	运行原始 GAQL 查询

示例命令

# Check which account you're working with
"What Google Ads account am I connected to?"

# List campaigns
"Show me all campaigns in this account"

# Create a new campaign
"Create a Search campaign for brand terms with $50/day budget"

# Check what's pending review
"What changes are pending my review?"

# After reviewing in Google Ads UI
"Enable the approved ads in the Brand campaign"

# Performance analysis
"Show me keyword performance for the last 30 days, sorted by cost"

# Run custom GAQL
"Run a GAQL query to get all ad groups with CTR below 2%"

示例：端到端创建 Demand Gen 广告系列

# 1. Campaign: $75/day, DEMAND_GEN channel, MAXIMIZE_CONVERSIONS default,
#    targeting Alaska (21134) + Maine (21141) in English
google_ads_create_campaign({
  name: "DG - Spring Promo",
  daily_budget: 75,
  channel_type: "DEMAND_GEN",
  geo_target_ids: ["21134", "21141"],
  start_date: "2026-05-01",
  end_date: "2026-06-30"
})
# → campaign_id: 555123

# 2. Ad group: DEMAND_GEN_MULTI_ASSET_AD_GROUP
google_ads_create_ad_group({
  campaign_id: "555123",
  name: "DG AG 1",
  type: "DEMAND_GEN_MULTI_ASSET_AD_GROUP"
})
# → ad_group_id: 555456

# 3. Image assets (PNG/JPG/GIF, ≥600×314, ≤5MB). Returns {asset_id, ...}
google_ads_create_image_asset({ name: "hero-landscape", file_path: "/abs/path/hero.png" })
# → asset_id: 42001
google_ads_create_image_asset({ name: "hero-square",    file_path: "/abs/path/square.png" })
# → asset_id: 42002
google_ads_create_image_asset({ name: "logo",           file_path: "/abs/path/logo.png" })
# → asset_id: 42003

# 4. Demand Gen multi-asset ad (PAUSED). Validates char + count caps first.
google_ads_create_demand_gen_multi_asset_ad({
  ad_group_id: "555456",
  final_urls: ["https://example.com/spring"],
  business_name: "Example Org",
  call_to_action: "LEARN_MORE",
  marketing_image_asset_ids: ["42001"],          // 1.91:1 landscape, ≥1 required
  square_marketing_image_asset_ids: ["42002"],   // 1:1 optional
  logo_image_asset_ids: ["42003"],               // logo optional
  headlines: ["Spring Sale Now On", "Save 20% Today"],     // max 5, ≤40 chars each
  long_headlines: ["A longer pitch under ninety characters."], // max 5, ≤90 chars
  descriptions: ["Shop the latest looks.", "Free returns."]   // max 5, ≤90 chars each
})
# → resource_name: customers/.../adGroupAds/555456~67890000

完成全部 4 次调用后，广告系列、广告组和广告都会以 PAUSED 状态保存在您的账户中，并标记为 Claude-MM-DD-YY。请在 Google Ads 界面中检查，然后通过 google_ads_enable_items 启用。

安全功能

1. 所有内容初始均为 PAUSED — 在您明确启用之前，不会有任何内容投放
2. 标签跟踪 — 所有由 Claude 创建的项目都会添加 claude-pending 标签
3. 验证 — 创建前会验证广告（标题/描述长度等）
4. 审批提示 — 在 Claude Code 中，enable_items 工具需要明确审批
5. 客户端隔离 — 工作目录决定使用哪个账户，从而避免不同客户端之间发生错误

添加新客户端

编辑 config.json 以添加客户端。将每个客户端映射到一个工作目录：

{
  "clients": {
    "client-slug": {
      "customer_id": "123-456-7890",
      "name": "Client Name",
      "folder": "/path/to/client/workspace"
    }
  }
}

无需重启服务 — 每次请求时都会读取配置。

故障排除

“找不到与工作目录对应的客户端”

• 确保您位于与 clients 条目之一匹配的文件夹中
• 检查配置中的文件夹路径是否与 config.json 中的路径完全一致

“开发者令牌尚未获批”

• 新的开发者令牌需要获得 Google 批准
• 等待批准期间请使用测试账户

“身份验证失败”

• 刷新令牌可能已过期 — 请重新生成
• 检查 client_id 和 client_secret 是否正确

许可证

MIT — 详情请参阅 LICENSE。