LoomaScale for Google Ads

google-ads-mcp

让 ChatGPT 或 Claude 在你托管的服务上运行 Google Ads 账户——读取效果数据、研究关键词、构建广告系列、编辑预算，并设置无法被模型绕过的支出限制。

通过经过身份验证的 MCP 端点提供 42 个工具。采用 MIT 许可证。提取自一项生产服务；自 2026 年起，该服务一直在 ChatGPT 内运行实际广告系列。

问题

让大模型接入 Google Ads API，听起来像是一个周末就能搞定的小项目。真正棘手的是以下这些：

难点	可能遇到的问题
开发者令牌访问级别	新令牌的访问权限是 测试账户，只能访问测试账户。首次运行会返回空列表，看起来像是出了故障。申请基本访问权限需要提交申请，而且要等几天
经理账户	listAccessibleCustomers 返回的几乎都是 MCC 账户，这些账户没有广告系列。实际投放广告的账户是其子账户，每个账户都要将 login-customer-id 设为找到该账户时所在的经理账户
微单位	API 使用百万分之一单位。5000000 的预算相当于 5 个货币单位；如果弄错 10⁶ 倍，就会造成实际支出事故
货币	金额不带货币单位。如果把 UAH 预算报告成 $，用户看到的数值就会是真实金额的 40 倍
GAQL	它不是 SQL。没有 JOIN，细分条件会改变一行数据的含义，而使用错误的细分条件会在不知不觉中让总数倍增
API 版本	按公布的计划停用。固定使用的版本一旦停用就会停止工作，而不是进入弃用阶段
大模型会试图花钱	它会提议启用广告系列、提高预算，或用真实广告系列“简单测试一下”

本服务会处理以上所有问题，并且默认拒绝最后一种操作。

它不会做什么

请在快速入门前阅读此部分——这涉及资金。

• 不会自动启用任何内容。 google_create_campaign 的架构中没有状态字段，因此模型无法创建已启用的广告系列。启用操作由单独的工具执行。
• 只有由此服务创建的广告系列才能通过它启用。 对于在 Google Ads 界面中创建的广告系列，服务会拒绝启用，因为其预算从未通过上限检查。
• 每次预算变更都会根据你设置的上限进行检查，上限以账户自身的货币计。服务会拒绝超出上限的变更，绝不会暗中降低预算以符合上限。
• 写入工具设有每日调用次数限制，因此循环调用不会造成数百次变更。
• **此外还有独立的失控循环防护机制：**在一个时间窗口内，密集发起的调用会被拒绝。
• **它不会判断用户是谁。**默认情况下，它是单操作员模式：一个密码、一个账户，不支持多用户登录。

快速入门

git clone https://github.com/loomascale/ads-mcp && cd ads-mcp
cp .env.example .env && $EDITOR .env      # every value is documented in place
docker compose up

然后打开 http://localhost:8080/connections，输入操作员密码，并连接 Google Ads 账户。

请将 MCP_DEFAULT_MAX_DAILY_BUDGET_CENTS 的初始值设低一些。这是防止模型动用你的银行卡的最后一道防线。

前置条件

Google Ads 开发者令牌。进入 Google Ads 经理（MCC）账户 → 工具和设置 → API 中心。申请基本访问权限；默认权限是测试账户访问权限，只能访问测试账户。这是首次运行看起来像出故障的最常见原因。审批需要几天——请从这里开始。

**Google Cloud OAuth 客户端。**在项目中启用 Google Ads API，然后进入“凭据” →“OAuth 客户端 ID”→“Web 应用”。将 http://localhost:8080/connect/google/callback 注册为获授权的重定向 URI；只要不完全一致，Google 就会以 redirect_uri_mismatch 拒绝请求。

**经理账户？**无需配置。连接流程会遍历每个可访问客户的账户树，跳过经理账户，并为每个账户记录正确的 login-customer-id。

连接客户端

ChatGPT 和 Claude 都需要一个以 /mcp 结尾的公开 HTTPS URL。它们会自行注册、完成 PKCE 流程，然后进入授权同意页面。

它们都无法连接 localhost，因此请使用隧道，而不是尝试直接连接：

cloudflared tunnel --url http://localhost:8080

将 OAUTH_ISSUER 设置为隧道的 https 源。客户端会从你的发现文档中读取颁发者，然后与文档指定的地址通信，因此值过时会导致问题，看起来像是客户端出错。

如需完全不使用客户端进行调试：

curl -s -X POST https://your-host/mcp \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

工具

共 42 个，名称均以 google_ 为前缀。读取工具需要 ads.read；写入工具需要 ads.write，并且必须通过上述防护措施。

账号与账单 — list_ad_accounts、check_billing、check_pacing、update_account_budget

广告系列 — list_campaigns、create_campaign、create_pmax_campaign、activate_campaign、set_status、update_budget、update_campaign_bidding、update_campaign_settings、update_campaign_targeting、update_campaign_negatives、update_campaign_conversion_goals

广告组与广告 — create_ad_group、update_ad_group、list_ads、create_ad、update_ad

关键字与搜索字词 — list_keywords、add_keywords、remove_keywords、update_keyword、list_search_terms、keyword_ideas

效果最大化广告系列 — list_asset_groups、update_asset_group、update_asset_group_assets、update_asset_group_media、update_search_themes、update_brand_assets

附加链接 — list_sitelinks、create_sitelinks、update_sitelink、remove_sitelinks

洞察 — get_insights、get_geo_insights、get_audience_insights、list_conversion_actions、update_conversion_action、find_locations

作为库使用

API 客户端单独发布，不依赖 Spring 和 MCP，适用于只需与 Google Ads 通信的代码：

<dependency>
  <groupId>com.loomascale</groupId>
  <artifactId>google-ads-client</artifactId>
  <version>0.1.0</version>
</dependency>

工具和服务名为 google-ads-mcp，基于 mcp-core 构建，后者提供协议层和 OAuth 2.1 授权服务器。此处的每个扩展点——凭据、配额、品牌、授权同意、审计——都可以通过声明一个 bean 来替换。

安全

凭据使用 AES-256-GCM 加密后静态存储。访问令牌使用签名密钥签名，该密钥必须与其他任何签名用途的密钥不同。授权码和刷新令牌经过哈希处理后存储，且只能使用一次；重复使用会撤销整个令牌家族。模型提供的图片 URL 在服务器获取任何内容之前，都会经过 SSRF 策略检查。工具参数绝不会被记录日志，只记录参数名称。

请在服务前配置 TLS。请私下报告漏洞：参见 SECURITY.md。

兼容性

google-ads-mcp	mcp-core	Google Ads API	Java
0.1.x	0.1.x	v21	21+

项目来源

从 LoomaScale 中提取。LoomaScale 是一款用于 Google Ads 的 AI 操作工具。这 42 个工具与其生产环境中运行的完全相同，并非精简版本；上述防护措施也正是保护真实账号的措施。

如果你不想自行托管，托管产品无需申请开发者令牌，也无需 OAuth 客户端：它从免费的 Google Ads 浪费审计开始，套餐信息请见定价页面。自托管是真正的替代方案，而非诱饵——本仓库没有隐藏任何内容。

无论选择哪种方式，都值得阅读以下两份指南，因为客户端侧的步骤对于连接你自己的服务也完全相同： ChatGPT · Claude。

贡献

请参阅 CONTRIBUTING.md——首先阅读 secrets 部分。

由 LoomaScale 构建并用于生产环境。采用 MIT 许可证。