Google Ads

影片展示的是使用示例数据的托管版 getmcpads。其中的 MCP Apps 功能，从创意图库和提醒，到 Google Sheets 导出和批量启动，都属于托管产品。本仓库提供独立的原生 API 工具。

35 个读取工具 · 13 个写入工具，默认禁用。

使用你自己的平台凭据，以及支持 stdio MCP 的客户端（例如 Claude Desktop、Claude Code 或 Cursor）在本地运行。请求会直接发送到平台。对于托管连接（包括受支持的 ChatGPT 配置），请使用托管版。

更新内容

v2.1.1：Zod 4 安全更新 · 2026 年 10 月 26 日

• 将 zod 更新至 4.6.7。所有早于 4.6.6 的 Zod 版本都受高危安全公告 GHSA-mrhx-c7xc-m3w5 影响：验证超大且受约束的集合可能耗尽内存，而且 Zod 3 没有任何版本包含此修复。npm audit --omit=dev 再次显示没有漏洞。
• 保留 Zod 3 的验证行为。参数默认值在使用前仍会经过验证和补全，因此省略的对象仍必须提供其必填字段。
• 参数为可选或有默认值时，保留各参数自身的描述。Zod 4 仅在包装后的架构上存储描述，否则共享的回退描述可能会取代它。
• 通过 MCP 发布的工具名称、参数和描述均未更改。server-card.json 已使用 Zod 4 的 JSON Schema 输出重新生成，部分约束的表述方式有所不同。

更早的版本

版本	日期	主要内容
2.1.0	2026 年 10 月 23 日	重命名、Google Ads API v26 和 Search Lift
2.0.1	2026 年 9 月 23 日	恢复公开仓库
2.0.0	2026 年 9 月 20 日	网关同步和安全修复
1.1.0	2026 年 9 月 13 日	平台能力同步和质量契约
1.0.2	2026 年 8 月 30 日	通过 MCP 公布软件包版本。
1.0.1	2026 年 8 月 30 日	添加 server.json 和 mcpName，以支持官方 MCP Registry，名称为 com.getmcpads/google-ads。
1.0.0	2026 年 8 月 29 日	首次开源发布

完整更新日志 · 所有版本

源同步说明：SOURCE_SYNC.md。

升级说明

需要 Node.js 22.23.4、24.22.1 或 26.12.1，或这些版本线中更新的版本。较旧版本缺少 2026 年 10 月的安全修复，服务器在这些版本上启动时会在 stderr 中打印警告。CI 覆盖 Node 22、24 和 26。

此版本未对配置做任何破坏性更改。针对 3.0.0，我们宣布两项变更：

• 在 2.x 中，GOOGLE_ADS_ACCOUNT_IDS 是可选的。设置后，所有工具都只能访问所列客户。未设置时，服务器会像以前一样启动，并在 stderr 中打印一行建议。它将在 3.0.0 中变为必填项。
• GOOGLE_ADS_ENABLE_WRITES 仍接受 1、yes 和 on，并会在 stderr 中打印一行弃用提示。请改用 true，这是 3.0.0 唯一接受的值。

服务器固定使用 Google Ads API v26。通过 google_ads_run_gaql 和 google_ads_run_readonly_rpc 发送的原始查询也遵循 v26。如果查询读取 customer.conversion_tracking_setting.enhanced_conversions_for_leads_enabled 或 ad_group_bid_modifier 的酒店字段，则必须使用 Google's v26 release notes 中列出的 v26 名称。写入功能仍为可选，并且需要明确确认。

安装此版本

这是一个 GitHub 源码版本。npm 和 MCP Registry 版本会单独发布。以下命令会选择此确切版本；本文档后面的未固定版本 npx 示例会选择 npm 上当前可用的版本。

git clone --branch v2.1.1 --depth 1 https://github.com/get-mcp-ads/google-ads-mcp-server.git
cd google-ads-mcp-server
npm ci
npm run build

配置 MCP 客户端，使其使用下方记录的平台凭据，通过绝对路径运行 dist/cli.js 的 node。

更倾向于托管连接？ 使用托管服务 getmcpads 访问 Google Ads。连接你的账号，选择助手可以访问的数据，然后使用托管 MCP 连接。当前功能和方案请参阅网站。

你将获得

35 个读取工具	广告系列、广告组、预算、出价策略、搜索字词、落地页、效果最大化系列素材和版位、购物、建议、变更历史
13 个写入工具	默认关闭。状态、预算、出价、投放时间表、重命名、创建广告系列。每项操作都会先预览，再执行
完整的 Keyword Planner	关键词创意、历史指标、预测、广告组主题、地理位置定位建议
145 个指标、88 个维度	附带兼容性矩阵，可在无效组合调用 API 前将其拦截
Google Ads API v26	此版本固定使用的版本，包括从 lift_measurement_config 读取的 Search Lift 指标
5 个资源	可供大模型读取的实时目录：指标、维度、兼容性规则、11 个工作流配方
GAQL 及更多功能	用于原始查询的 google_ads_run_gaql，以及用于访问 GAQL 无法触达的服务的 google_ads_run_readonly_rpc

你不需要了解 GAQL

Google Ads API 使用其专属查询语言 GAQL 进行查询，其大部分功能只能通过这种方式访问。此服务器内置了指标和维度目录，因此大模型只需按名称请求 cost 和 conversions，服务器就会编写查询。

google_ads_validate_query 可让它在调用 API 前检查组合，而你仍可在需要自行编写 GAQL 时使用 google_ads_run_gaql。

Keyword Planner 不属于 GAQL

关键词创意、历史搜索量和预测数据都位于独立的 RPC 服务中，GAQL 完全无法访问这些数据。Reach Planner、受众洞察和基准数据也是如此。此服务器通过 google_ads_run_readonly_rpc 和专用工具提供这些功能。

---

获取凭据

在所有广告平台中，此平台的设置最繁琐。需要四个值，其中一个需要经过 Google 审核。首次设置请预留一小时。

1. 开发者令牌

使用经理（MCC）账号，打开工具 → API Center并申请令牌。 令牌初始为测试账号级别，只能访问测试账号。申请Basic Access即可访问正式账号。Google 会审核申请，可能需要几天时间。

📖 开发者令牌文档

2. OAuth 客户端

在 Google Cloud 项目中启用 Google Ads API， 然后在 APIs & Services → Credentials 下创建 OAuth 客户端。本地使用时请选择 Desktop app。记下客户端 ID和客户端密钥。

3. 刷新令牌

使用可查看广告账号的 Google 账号登录，运行一次 OAuth 授权流程，并保存返回的刷新令牌。Google 自己的辅助脚本可通过一条命令完成此操作。

📖 OAuth 桌面流程

刷新令牌不会过期。 这是此处需要妥善保管的敏感值：持有它的任何人都可以无限期地生成访问令牌。请像对待密码一样保管它，并为此服务专门使用一个 OAuth 客户端，以便可以单独撤销该令牌。

4. 登录客户 ID（使用经理账号时）

如果要查询的账号位于 MCC 下，请将 GOOGLE_ADS_LOGIN_CUSTOMER_ID 设为经理账号 ID。可以使用带短横线的 ID，系统会自动移除短横线。独立账号无需设置。

也可以不设置此变量。对于受管理的账号，Google 会拒绝所有未注明其经理的请求，并返回 USER_PERMISSION_DENIED，但错误中既不提账号，也不提经理，因此看起来像是缺少访问权限，而不是缺少请求头。如果未设置该变量，且要查询的账号无法直接访问，服务会询问它能够访问的经理账号，这些经理账号中哪些持有该账号，并告知你匹配的经理账号。答案只会解析一次，并在进程运行期间保留。

设置此变量仍然更快：这样可以完全跳过发现过程。如果你查询的所有账号都位于同一个 MCC 下，这也是正确的选择。

请将 google_ads_health_check 作为首次调用。它会验证全部四项凭据，列出你实际可以访问的账号，并报告缺少的内容，同时不会打印任何密钥。

---

设置

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "@getmcpads/google-ads-mcp-server"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_CLIENT_ID": "your-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_ACCOUNT_IDS": "123-456-7890"
      }
    }
  }
}

重启 Claude Desktop。向它提问："列出我的 Google Ads 账号"。

Claude Code

claude mcp add google-ads --env GOOGLE_ADS_DEVELOPER_TOKEN=... --env GOOGLE_ADS_CLIENT_ID=... --env GOOGLE_ADS_CLIENT_SECRET=... --env GOOGLE_ADS_REFRESH_TOKEN=... -- npx -y @getmcpads/google-ads-mcp-server

Cursor

在项目中的 .cursor/mcp.json 文件中配置，格式与上面的 Claude Desktop 配置相同。

从源代码运行

git clone https://github.com/get-mcp-ads/google-ads-mcp-server.git
cd google-ads-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in your credentials
npm start

配置

变量	默认值	含义
GOOGLE_ADS_DEVELOPER_TOKEN	none	必需。 从 API Center 获取，需为 Basic Access 或更高级别
GOOGLE_ADS_CLIENT_ID	none	必需。 OAuth 客户端 ID
GOOGLE_ADS_CLIENT_SECRET	none	必需。 OAuth 客户端密钥
GOOGLE_ADS_REFRESH_TOKEN	none	必需。 从授权流程获取
GOOGLE_ADS_LOGIN_CUSTOMER_ID	none	可选。经理（MCC）账号 ID。未设置时会自动解析
GOOGLE_ADS_ACCOUNT_IDS	未设置	建议设置。逗号分隔的客户 ID，所有工具都只能访问这些账号。未设置时，凭据可访问的所有账号均可用。3.0.0 版本中为必需
GOOGLE_ADS_ENABLE_WRITES	未设置	设为 true 以注册 13 个写入工具。1、yes 和 on 仍可使用，但会打印弃用提示
LOG_LEVEL	info	debug、info、warn、error

你可以随时检查设置：

npm run doctor

---

写入操作及其为何先预览

写入工具默认处于禁用状态。使用 GOOGLE_ADS_ENABLE_WRITES=true 启用。 Google 自家的 Google Ads MCP server 仅支持读取，因此请仔细阅读这一部分。

启用后，每个写入工具都会返回预览，且不会更改任何内容：

// google_ads_update_campaign_budget { customerId: "123-456-7890", budgetId: "555", dailyAmount: 50 }
{
  "applied": false,
  "action": "google_ads_update_campaign_budget",
  "change": { "customer": "1234567890", "budget": "555",
              "newDailyBudget": 50, "inMicros": 50000000 },
  "message": "Preview only, nothing was changed. Repeat the same call with confirm: true to apply this change to the live account."
}

只有第二次调用携带 confirm: true 时，才会修改实时账户。

这是刻意设计的。助手会编排这些调用，但可能选错客户、选错广告系列，或把预算的数量级设错。强制预览能让错误在造成损失前显现，并为人工审核提供一个停止点——协议本身无法保证这一点。

另外还有两道防护措施：

• google_ads_create_campaign 始终会创建状态为 PAUSED 的广告系列。 没有选项可以将其创建为启用状态。必须有人先检查，之后它才会开始花费。
• 金额会自动转换为微单位。 Google 以百万分之一为单位记录金额，因此账户货币中的 12.50 会转换为 12500000。预览会同时显示两种数值，因此在应用前就能发现千倍的差错。

工具	更改内容
google_ads_update_campaign_status / google_ads_update_adgroup_status	暂停、重新启用或移除
google_ads_update_campaign_budget	每日预算
google_ads_update_adgroup_bid	默认 CPC 出价
google_ads_update_campaign_schedule	开始和结束日期
google_ads_rename_campaign / google_ads_rename_adgroup / google_ads_rename_asset_group / google_ads_rename_account	仅修改名称。无法重命名广告：Google 会将广告名称设为不可变
google_ads_create_campaign	创建预算，然后创建广告系列，状态始终为 PAUSED

---

工具

下方列出了所有工具。完整的参数和输出架构请参见 server-card.json。

35 个读取工具

| 工具 | 用途 | | --- | --- | | `google_ads_list_accounts` | 列出使用当前凭据可访问的 Google Ads 客户账号。 | | `google_ads_get_account_details` | 获取特定 Google Ads 客户账号的详细信息。 | | `google_ads_run_gaql` | 执行原始 GAQL（Google Ads Query Language）查询。 | | `google_ads_get_insights` | 通过智能查询规划查询 Google Ads 效果洞察。 | | `google_ads_get_campaigns` | 列出 Google Ads 账号的广告系列及其状态、预算、渠道类型和出价策略。 | | `google_ads_get_adgroups` | 列出 Google Ads 账号的广告组，可按广告系列筛选。 | | `google_ads_get_keyword_performance` | 从 keyword_view 资源获取关键词级效果数据。 | | `google_ads_validate_query` | 在执行查询前验证指标／维度／资源是否兼容。 | | `google_ads_health_check` | 只读连接检查。 | | `google_ads_get_account_hierarchy` | 列出可访问的客户，并在可能时通过 GAQL customer_client 获取经理／客户关系。 | | `google_ads_get_conversion_actions` | 列出转化操作及其状态、类型、类别、主要／计入转化标志、所有者客户，以及受支持时的最近活动日期。 | | `google_ads_get_change_events` | 获取近期的 change_event 行。 | | `google_ads_get_recommendations` | 列出 Google Ads 建议及其类型、资源、广告系列／广告组关联、已忽略状态，以及受支持时的影响。 | | `google_ads_get_budgets` | 列出广告系列预算及其金额、状态、投放方式，以及受支持时的建议预算字段。 | | `google_ads_get_bidding_strategies` | 列出组合出价策略。 | | `google_ads_get_search_terms` | 根据 reportType，从 search_term_view 或 campaign_search_term_insight 获取搜索字词效果。 | | `google_ads_get_landing_pages` | 获取 landing_page_view 效果数据，包括最终 URL、广告系列／广告组上下文、流量、转化，以及受支持时的着陆页质量指标。 | | `google_ads_get_pmax_assets` | 从 asset_group_asset 列出效果最大化广告系列的素材资源组素材资源，包含素材资源组／广告系列上下文，以及可选的日期范围效果指标。 | | `google_ads_get_simulations` | 用于广告系列、广告组或组合出价模拟的只读规划／预测查询。 | | `google_ads_get_paid_organic_search_terms` | 只读付费／自然搜索字词报告。 | | `google_ads_get_shopping_products` | 通过 shopping_product 获取只读 Merchant Center 产品目录／资格报告。 | | `google_ads_get_shopping_performance` | 按 Merchant Center 产品维度提供的只读购物效果报告。 | | `google_ads_get_pmax_placements` | 从 performance_max_placement_view 获取只读效果最大化广告系列版位诊断信息。 | | `google_ads_get_pmax_asset_diagnostics` | 只读效果最大化广告系列素材资源组诊断信息。 | | `google_ads_list_image_assets` | 列出账号的图片素材资源库（FROM asset），包含位于 tpc.googlesyndication.com、可稳定公开访问的原尺寸 URL、尺寸、文件大小和 MIME 类型。 | | `google_ads_list_video_assets` | 列出账号的 YouTube 视频素材资源（FROM asset），并提供生成的观看、嵌入和公开缩略图 URL。 | | `google_ads_get_demand_gen_assets` | 列出需求开发广告（视频自适应、多素材资源、轮播），并解析其引用的创意素材：稳定的图片 URL，以及带嵌入和缩略图 URL 的 YouTube 视频 ID。 | | `google_ads_generate_keyword_historical_metrics` | 获取所提供关键词的 Keyword Planner 搜索量历史记录。 | | `google_ads_generate_keyword_ideas` | 从最多 20 个种子关键词、一个 URL、关键词加 URL 或整个网站中发现 Keyword Planner 创意。 | | `google_ads_generate_keyword_forecast_metrics` | 预测临时关键词广告系列的点击次数、CPC、费用、转化次数和 CPA。 | | `google_ads_search_fields` | 搜索 Google 实时 GoogleAdsField 目录。 | | `google_ads_suggest_geo_targets` | 将最多 25 个地理位置名称或地理目标 ID 解析为 Google Ads geoTargetConstants。 | | `google_ads_generate_ad_group_themes` | 将提供的关键词归入现有 Google Ads 广告组。 | | `google_ads_run_readonly_rpc` | 面向 GAQL 以外允许列表中的 Google Ads 服务的高级只读备用接口：受众洞察、覆盖面规划工具、基准数据、创作者／趋势洞察、定位建议、智能广告系列建议、身份验证、发票和付款账号。 | | `google_ads_get_video_upload` | 读取所选客户中一项 Google Ads 上传内容的处理状态和 YouTube 视频 ID。 |

13 个写入工具

默认禁用。除非明确确认，否则调用仅会预览。使用前请检查配置和准确的架构。

工具	用途
google_ads_upload_video	将 MP4/WebM/QuickTime 文件（最大 16 MiB）上传到所选广告账号对应的 Google 管理的 YouTube 频道。
google_ads_remove_video_upload	删除由所选广告账号上传的视频。
google_ads_apply_plan	预览、验证并原子化应用 Google Ads v26 构建/更改计划：广告系列、预算、广告组、RSA/展示广告/需求开发广告、图片/文本/YouTube 资源、效果最大化广告系列资源组及其链接、关键字、地理位置/语言定位、商品列表组以及转化操作配置（不包含转化事件上传）。
google_ads_update_campaign_status	暂停、重新启用或移除 Google Ads 广告系列。
google_ads_create_campaign	创建 Google Ads 广告系列。
google_ads_update_campaign_budget	更改 Google Ads 广告系列的每日预算。
google_ads_rename_campaign	重命名 Google Ads 广告系列。
google_ads_rename_adgroup	重命名 Google Ads 广告组。
google_ads_rename_asset_group	重命名 Google Ads 效果最大化广告系列资源组。
google_ads_rename_account	重命名 Google Ads 账号（其描述性名称）。
google_ads_update_campaign_schedule	更改 Google Ads 广告系列的开始或结束日期。
google_ads_update_adgroup_status	暂停、重新启用或移除 Google Ads 广告组。
google_ads_update_adgroup_bid	更改 Google Ads 广告组的默认 CPC 出价。

5 个资源

URI	内容
google-ads://manifest	此服务提供的内容，以及应首先运行的工具
google-ads://metrics	全部 145 项指标及其类别和格式
google-ads://dimensions	全部 88 项维度及其适用范围
google-ads://compatibility	兼容性矩阵
google-ads://recipes	11 个分步工作流

---

安全性

此服务持有一个永不过期的刷新令牌、一个客户端密钥和一个开发者令牌。 具体而言：

• 这四项凭据均绝不会被记录到日志中，无论日志级别如何，也不会写入磁盘。
• 访问令牌会缓存于内存中，直到过期前一分钟，而不是每次调用都重新请求。读取和写入共用该令牌。
• 刷新令牌被撤销时只会报告一次。 当 Google 返回 invalid_grant 后，所有后续调用都会返回相同消息，并附上重新授权的步骤；服务也会停止向 Google 请求令牌，直到重启。
• 可以限制账号范围。 设置 GOOGLE_ADS_ACCOUNT_IDS 后，任何指定其他客户的调用都会在发出请求前被拒绝，账号发现也只会列出获准访问的客户。
• 仅会联系两个主机，且只有两个：googleads.googleapis.com 和 oauth2.googleapis.com。如果源码中出现第三个主机，测试将导致构建失败。
• 不会跟随重定向进行获取。 每个出站调用都设置 redirect: "error"，因此重定向无法将持有者令牌或客户端密钥转发到其他主机。如果有任何 fetch 调用未设置此项，测试将导致构建失败。
• 无遥测数据。 除了联系 Google，此服务不会进行任何网络调用。

完整政策和报告说明：SECURITY.md。

---

正在寻找托管式、多平台版本？

如果你想使用此数据源，但不想运行本地服务，请试用托管版 Google Ads。 getmcpads 还可通过一个 MCP URL 连接广告、Search Console 和 GA4。 数据源可用情况和套餐限制请查看网站；仍需连接账户。

1. 按照 Google Ads 连接指南操作。
2. 选择助手可以读取的账户或资源。
3. 连接 Claude、 ChatGPT 或 Codex。
4. 尝试只读检查：“比较相同时间段内的广告系列支出和转化次数。指出缺失的数据，不要进行任何更改。”

选择付费套餐前，请查看当前托管工具目录 和定价。 此 Apache 2.0 适配器仍可使用你自己的凭据独立运行。

---

贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。 报告任何安全相关问题前，请阅读 SECURITY.md。

许可证

Apache License 2.0。另请参阅 NOTICE。

Google、Google Ads 和 Google Ads API 是 Google LLC 的商标。 本项目与 Google LLC 无关联，也未获得其认可或赞助。 这是一个独立的公共 API 客户端。

MCP 合约与桌面版套件

每个工具都声明读写注解、参数说明和结构化输出架构。成功调用会在 structuredContent.result 中提供负载；错误会保留 isError: true。生成的服务器卡片仅包含定义。

运行 npm run bundle -- /path/to/output，即可根据当前目录构建 .mcpb 桌面套件。安装期间需在本地输入凭据。除非明确启用，否则写入工具将保持禁用。

更多 getmcpads 项目

Meta Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

由 getmcpads 的 Emmanuel 维护。问题请联系：[email protected]。