google-ads-mcp

用途

google-ads-mcp 是一个 MCP（Model Context Protocol）服务器配置方案，用于为 Claude Code、Claude Desktop、Cursor 或其他 MCP 客户端提供对 Google Ads API 的实时访问能力。当用户希望将 Claude 连接到自己的 Google Ads 账户时，可启用该配置。

安装与运行

安装命令：

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

运行方式：

python -m ads_mcp.server

凭据配置

可通过 .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

各凭据的获取位置：开发者令牌来自 ads.google.com 的 Tools & Settings → API Center；Client ID 与 Client Secret 来自 console.cloud.google.com 的 Credentials；Refresh Token 可通过 OAuth Playground 或 google-ads Python 认证辅助工具生成；Login Customer ID 为 MCC 账户 ID（位于 Google Ads 界面顶部）。

客户端配置

Claude Code：在项目根目录放置 .mcp.json，Claude Code 会自动发现并在启动时加载服务器：

{
  "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 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：关键词规划师搜索量与 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 个，默认 dry-run）

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 mutation

所有写入工具默认 confirm=False，即仅生成 dry-run 预览；需在审阅预览后传入 confirm=True 才会实际执行。

文档工具（2 个）

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

适用场景

适合需要在 AI 客户端中直接查询 Google Ads 账户数据、分析广告系列/关键词/搜索词表现、审阅竞价与地域/设备表现，并在预览确认后调整预算、状态、出价或添加关键词的投放与优化工作。

限制与排错

UNAUTHENTICATED：刷新令牌过期，需通过 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 智能体；googleadsagent.ai 为生产系统（Buddy）。