google-ads-mcp

Google Ads MCP 服务

这项技能可为 google-ads-mcp 服务配置实时 Google Ads API 访问，适用于 Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端。

快速设置

1. 安装

pip install git+https://github.com/itallstartedwithaidea/google-ads-mcp.git

2. 配置凭据

创建 .env 文件或设置环境变量：

GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token
GOOGLE_ADS_CLIENT_ID=your-oauth-client-id
GOOGLE_ADS_CLIENT_SECRET=your-oauth-client-secret
GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

或者指向现有的 google-ads.yaml：

GOOGLE_ADS_CREDENTIALS=/path/to/google-ads.yaml
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

3. 运行

python -m ads_mcp.server

Claude Code 配置

将 .mcp.json 放在项目根目录：

{
  "mcpServers": {
    "google-ads": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "ads_mcp.server"],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "${GOOGLE_ADS_CREDENTIALS}",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "${GOOGLE_ADS_LOGIN_CUSTOMER_ID}"
      }
    }
  }
}

Claude Code 会自动发现 .mcp.json，并在启动时加载服务。

Claude Desktop 配置

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "ads_mcp.server"],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "/path/to/google-ads.yaml",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "123-456-7890"
      }
    }
  }
}

可用工具（29 个）

读取工具（9 个）

工具	说明
list_accessible_customers	列出所有可访问的客户账户
list_accounts	列出 MCC 下的账户及详情
execute_gaql	运行自定义 GAQL 查询
get_campaign_performance	按日期范围查看广告系列指标
get_keyword_performance	查看关键词指标和质量得分
get_search_terms	查看包含无效支出数据的搜索字词报告
get_ad_performance	查看广告创意效果
get_account_budget_summary	分析预算使用情况
generate_keyword_ideas	查看 Keyword Planner 搜索量和每次点击费用（CPC）

审核工具（7 个）

工具	说明
get_auction_insights	竞争性拍卖数据
get_change_history	近期账户变更
get_device_performance	按设备类型查看效果
get_geo_performance	按地理位置查看效果
get_recommendations	Google 的优化建议
get_pmax_performance	Performance Max 广告系列数据
get_impression_share	展示份额和错失机会

写入工具（11 个）— 默认采用试运行模式

工具	说明
update_campaign_budget	更改每日预算
update_campaign_status	暂停或启用广告系列
update_ad_group_status	暂停或启用广告组
update_keyword_bid	更改关键词的 CPC 出价
add_keywords	向广告组添加关键词
add_negative_keywords	添加否定关键词
remove_negative_keyword	移除否定关键词
create_campaign	创建新的广告系列（已暂停）
create_ad_group	创建新的广告组
switch_bidding_strategy	更改出价策略
generic_mutate	原始 Google Ads API 修改操作

所有写入工具默认使用 confirm=False（试运行预览）。只有在检查预览后，才传入 confirm=True。

文档工具（2 个）

工具	说明
get_gaql_reference	GAQL 语法和字段参考
get_workflow_guide	分步工作流说明

凭据来源

值	获取位置
Developer Token	ads.google.com → Tools & Settings → API Center
Client ID	console.cloud.google.com → Credentials
Client Secret	console.cloud.google.com → Credentials
Refresh Token	OAuth Playground 或 google-ads Python 身份验证辅助工具
Login Customer ID	你的 MCC 账户 ID（位于 Google Ads 界面顶部）

故障排除

问题	解决方法
UNAUTHENTICATED	Refresh Token 已过期 — 通过 OAuth Playground 重新生成
PERMISSION_DENIED	你的 MCC 下无法访问该账户
DEVELOPER_TOKEN_NOT_APPROVED	在 ads.google.com → API Center 申请 Basic Access
超出速率限制	Basic Access：每天 15K 次操作。使用 LIMIT 子句和筛选条件。

相关资源

• google-ads-mcp 仓库 — 完整源代码
• google-ads-api-agent — 包含 28 个工具的 Python Agent
• googleadsagent.ai — 生产系统（Buddy）