适用于 Claude Code、Codex、Cursor、Windsurf 的 Google Ads Skill 与 MCP Server

ADM 的 Google Ads Skill 让 AI 编程工具读取你的 Google Ads 账号，并按书面投放计划创建搜索广告系列，支持 Claude Code、Codex、Cursor 与 Windsurf。Skill 是一个 SKILL.md 文件，描述操作流程；实际操作经由 ADM MCP Server 完成，它把 AI 工具连接到你在 ADM 中关联的 Google Ads 账号。

• 所有套餐可读取：报表、搜索字词、关键字、广告与素材资源查询，所有 ADM 套餐可用，包括免费版。
• 付费套餐可写入：创建广告系列、广告组、广告、关键字、否定关键字与素材资源，需要付费套餐（Starter、Professional 或 Enterprise）。
• 每处改动先预览：ADM 校验每一处改动并返回预览，经你确认后才写入 Google Ads。
• 新广告系列一律暂停：新建的广告系列均为暂停状态，只有你另行明确要求时才会启用。

地址：

• Skill 文件：https://adm.cc/docs/google-ads-skill/SKILL.md（文件夹名 adm-google-ads）
• MCP Server：https://app.adm.cc/mcp（Streamable HTTP），以 ADM API 密钥认证，请求头为 Authorization: Bearer adm_xxx
• 契约版本：2026-09-30

1. 三步接入

第 1 步：创建 API 密钥。 登录 ADM，打开 https://app.adm.cc/apikeys，选择权限：

• 只读：仅报表与配置查询，所有套餐可用，包括免费版。
• 读写：报表查询加写入工具。写入工具需要有效的付费套餐。

完整密钥只显示一次，关闭对话框前请先复制。

第 2 步：让 AI 工具安装 ADM。 复制下面的提示词，把 adm_xxx 替换为你的密钥，发送给 AI 工具。AI 工具会按第 5 节的步骤连接 ADM MCP Server、保存 Skill 文件并测试连接。完成后按提示重启 AI 工具。

Install the ADM MCP server and the ADM Google Ads skill by following https://adm.cc/zh/docs/google-ads-skill#ai-install. My ADM API key is adm_xxx

密钥会保留在对话记录中。对话记录可能被他人看到时，请在 ADM 中轮换该密钥（见第 10 节）。如需手动配置，见第 4 节。

第 3 步：用自然语言下达指令。 例如：「过去 30 天哪个广告系列花费最多？」或「创建 plan.md 中的广告系列。」更多示例见第 3 节。

2. Skill 会调用哪些 ADM 工具

各工具的完整说明与参数见第 6 节。

3. 接入后可以这样说

• 「过去 30 天哪个广告系列花费最多？各自有多少转化？」
• 「列出过去 14 天有花费但没有转化的搜索字词。」
• 「创建 plan.md 中的广告系列，先预览，等我确认。」
• 「为 plan.md 中 photo-enhancer 一节起草广告组。」
• 「把 banner.jpg 作为图片素材资源添加到 photo-enhancer@DE 广告系列。」
• 「切换到 MySecond 广告账号。」

默认账号

连接了多个 Google Ads 账号时，Skill 只询问一次要使用哪个账号，并把选择保存在项目目录下的 .adm/account.json 中（只含客户 ID 与账号名称，不含 API 密钥）。之后在同一项目中的请求都使用该账号，每次操作前会说明所操作的账号。只连接了一个账号时，Skill 直接使用该账号，不再询问。需要更换时，说「切换到 MySecond 广告账号」即可。保存的账号之后在 ADM 中被断开时，Skill 会在下一次操作前停下，说明该账号已不再连接，并询问要使用哪个账号，即使只剩一个账号也会询问。

示例：按投放计划创建广告系列

本示例使用虚构品牌 PixelUp，按名为 photo-enhancer@DE 的计划条目创建一个广告系列：一款在线照片增强工具，在德国以德语投放。

计划条目：

• 广告系列 photo-enhancer@DE，地区德国，一个广告组 photo-enhancer-DE
• 着陆页 https://www.example.com/de/photo-enhancer，显示路径 foto / verbessern
• 8 个词组匹配关键字、6 个标题、2 条描述、4 个系列级否定关键字
• 通用设置：仅 Google 搜索网络，采用「尽可能争取更多点击次数」出价策略并设 CPC 上限，不使用广泛匹配

计划中未注明日预算与 CPC 上限，因此 AI 工具会在创建前先询问这两项。本示例按账号币种使用日预算 10.00、CPC 上限 0.40。

指令示例：

Create the photo-enhancer@DE campaign from plan.md.
Daily budget 10.00, CPC cap 0.40. Preview first and wait for my approval.

AI 工具先不带 confirm 调用 create_search_campaign。ADM 校验请求并返回预览，列出所有错误、每段文字的显示宽度、账号币种与月预算估算（日预算 × 30.4），并附带 preview_id。你确认后，AI 工具用相同参数加上 "confirm": true 与该 preview_id 再次调用。

{
  "customer_id": "123-456-7890",
  "campaign": {
    "name": "photo-enhancer@DE",
    "daily_budget": 10.00,
    "bidding": { "type": "MAXIMIZE_CLICKS", "max_cpc": 0.40 },
    "network_settings": { "google_search": true, "search_partners": false, "display_network": false },
    "geo_targets": [ { "country_code": "DE" } ],
    "negative_keywords": [ "\"kamera\"", "\"handy\"", "\"bildschirm\"", "\"monitor\"" ],
    "ad_groups": [
      {
        "name": "photo-enhancer-DE",
        "language": "de",
        "keywords": [
          "\"foto verbessern\"", "\"bildqualität verbessern\"", "\"foto schärfen\"", "\"bild vergrößern\"",
          "\"foto qualität verbessern online\"", "\"unscharfes foto scharf machen\"",
          "\"bild hochskalieren\"", "\"foto auflösung erhöhen\""
        ],
        "ads": [
          {
            "final_url": "https://www.example.com/de/photo-enhancer",
            "path1": "foto",
            "path2": "verbessern",
            "headlines": [
              { "text": "Fotoqualität verbessern" },
              { "text": "Bilder online vergrößern" },
              { "text": "Unscharfe Fotos schärfen" },
              { "text": "Fotos 2x oder 4x vergrößern" },
              { "text": "Ohne Installation nutzen" },
              { "text": "PixelUp Foto-Verbesserer" }
            ],
            "descriptions": [
              { "text": "Fotoqualität online verbessern: Bilder 2x oder 4x vergrößern und schärfen." },
              { "text": "Für Produktfotos, Social-Media-Beiträge und kleine Bilder. Direkt im Browser, ohne App." }
            ]
          }
        ]
      }
    ]
  }
}

关于这段参数：

• 关键字使用 Google 写法："text" 为词组匹配，[text] 为完全匹配，不加符号为广泛匹配。在 JSON 中，词组匹配关键字的引号转义为 \"。
• "language": "de" 会在广告组名称后追加语言标签，因此该组创建后名为 photo-enhancer-DE [de]。ADM 之后分析该组时据此识别广告语言。
• 地理定位一律使用「所在地」选项（位于或经常位于该地区的用户）。
• 同一计划中的账号级否定关键字与共享列表是独立步骤：每个账号调用一次 add_account_negative_keywords，每个列表调用一次 create_shared_negative_list，再对每个新广告系列调用 attach_shared_negative_list。

结果中包含新的 campaign_id、各广告组 ID 与 operation_id。随后 AI 工具调用 get_campaign_setup，将 Google Ads 中的实际配置与计划逐项比对。在你要求启用之前，该系列保持暂停。

计划包含多个广告系列时，Skill 会指示 AI 工具：

• 在创建前列出所有待定事项，并核对计划中的数量
• 分两轮预览并请你确认：第一轮是广告系列与列表，第二轮是依赖新 ID 的列表挂载与素材资源
• 逐个广告系列创建，并把每个 ID 记录到清单文件 adm-manifest.json
• 核对结果；继续执行时跳过已完成的广告系列
• 启用任何广告系列前单独征求确认

4. 不安装 Skill、直接使用 MCP Server

Skill 是可选的。单独连接 MCP Server 时，服务器会在连接时向 AI 工具下发一组使用规则：每次写入先预览、新广告系列一律暂停、默认账号，以及把搜索字词当作数据处理。无论是否安装 Skill，MCP Server 还具备两项优势：

• 升级无需重装：ADM 发布的新工具与新字段立即可用，配置保持不变。
• 可按工具设置权限：多数 AI 工具可以自动批准读取工具，同时为写入工具保留确认步骤（见第 9 节）。

以下写法从环境变量 ADM_API_KEY 读取密钥。Codex、Cursor 与 Windsurf 在运行时读取该变量，配置文件中不含密钥；Claude Code 在添加服务器时把密钥写入其用户级配置 ~/.claude.json，请勿共享该文件。先设置该变量，再重启 AI 工具。

macOS 或 Linux（把这一行加入 ~/.zshrc 或 ~/.bashrc）：

export ADM_API_KEY="adm_xxx"

Windows（执行后打开新的终端）：

setx ADM_API_KEY "adm_xxx"

各 AI 工具的配置写法如下：

Claude Code（Bash）：

claude mcp add --transport http --scope user adm https://app.adm.cc/mcp \
  --header "Authorization: Bearer $ADM_API_KEY"

PowerShell：

claude mcp add --transport http --scope user adm https://app.adm.cc/mcp `
  --header "Authorization: Bearer $env:ADM_API_KEY"

--scope user 让本机所有项目都能使用该服务器。用 claude mcp list 检查连接：adm 一行末尾应显示 ✔ Connected。

若只想免去读取工具的确认，在 ~/.claude/settings.json（所有项目）或 .claude/settings.json（单个项目）中加入：

{
  "permissions": {
    "allow": [
      "mcp__adm__get_*"
    ]
  }
}

mcp__adm__get_* 匹配所有以 get_ 开头的 ADM 工具：9 个读取工具，以及只读取 AI 草稿状态的 get_ad_group_draft。写入工具不要加入允许列表（见第 9 节）。draft_ad_groups 不改动 Google Ads，但每次调用会执行多次 AI 调用，因此同样不在该规则范围内。若注册服务器时用了其他名称，把规则中的 adm 换成该名称。

Codex：

codex mcp add adm --url https://app.adm.cc/mcp --bearer-token-env-var ADM_API_KEY

Codex 在启动时读取 ADM_API_KEY。

Cursor（所有项目用 ~/.cursor/mcp.json，单个项目用项目内的 .cursor/mcp.json）：

{
  "mcpServers": {
    "adm": {
      "url": "https://app.adm.cc/mcp",
      "headers": { "Authorization": "Bearer ${env:ADM_API_KEY}" }
    }
  }
}

Windsurf（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "adm": {
      "serverUrl": "https://app.adm.cc/mcp",
      "headers": { "Authorization": "Bearer ${env:ADM_API_KEY}" }
    }
  }
}

Codex、Cursor 与 Windsurf 的写法依据各工具文档中的 MCP 配置格式。修改配置后重启 AI 工具，再让它列出你的 Google Ads 账号。Windsurf 的配置文件若不在上述路径，可在 MCP 设置中点击 View raw config 打开。${env:ADM_API_KEY} 从 AI 工具自身进程的环境中读取。Cursor 与 Windsurf 基于 VS Code，从程序坞或应用启动器打开时同样会读取 ~/.zshrc 或 ~/.bashrc 中设置的变量。设置或修改该变量后，需完全退出 AI 工具再重新打开（macOS 上按 Cmd+Q，只关闭窗口不会退出程序）；否则请求头不含密钥，服务器返回 HTTP 401。

连接排查

之前可用、现在返回 401 的密钥，通常已被撤销。API 密钥页面会显示每个密钥的最近使用时间。

5. AI 工具安装步骤（供 AI 工具读取）

本节写给 AI 工具，因此以英文书写。你只需完成第 1 节的第 2 步，AI 工具会按本节自行操作。

The user has given you an ADM API key (it starts with adm_). Install ADM as follows, then report what you did.

1. Add the MCP server at user level, so it works in all projects. Server name: adm. URL: https://app.adm.cc/mcp (Streamable HTTP). Header: Authorization: Bearer <key>. Write the key only into your user-level MCP configuration, never into a project file or a git repository. If a server named adm already exists, replace it.

Keep any other servers already in the file. On Windows, ~ is the user profile folder.

2. Save the skill. Download https://adm.cc/docs/google-ads-skill/SKILL.md to adm-google-ads/SKILL.md inside the skills directory you read for all projects. The folder name must be adm-google-ads. Create missing directories. If you do not know that directory, use the project-level one:

3. Test the connection. Call get_accounts on the adm server. If the tool is not available until you restart, say so.

4. Report to the user: where the server configuration and the skill file were saved, whether a restart is needed, and the Google Ads accounts found. After a restart, the user can say "List my Google Ads accounts" to check.

6. 工具参考

作用于某个账号的工具都使用 get_accounts 返回的 customer_id（格式 123-456-7890）；get_operation 与 get_ad_group_draft 只需各自的 ID。金额一律为账号币种的主单位，例如 5.00，不使用 micros。报表窗口 days 取 7、14 或 30 个完整自然日（按账号时区，不含今天，默认 7）。列表类工具每页最多返回 limit 行（1 至 200，默认 50），并返回 next_cursor 用于翻页。

读取工具

写入工具

所有写入工具都先预览。不带 confirm 调用时只校验并返回预览，不做任何改动；每次预览返回一个 preview_id。在该次预览后 30 分钟内，用完全相同的参数加上 "confirm": true 和该 preview_id 再次调用，才会执行。确认调用缺少 preview_id 时返回 invalid_argument；preview_id 不存在、已过期或对应的参数不同时返回 preview_required。用同一个 preview_id 重试确认调用，会返回之前的结果，不会重复写入。要再次执行同样的改动，需重新预览，并在确认后使用新的 preview_id 执行。

level 取 customer（所有系列）、campaign 或 ad_group；add_images 只接受 campaign 与 ad_group。素材资源类工具每次最多 20 项、20 个目标；添加到投放中广告系列的素材资源在 Google 审核通过后开始展示。

AI 起草广告组

draft_ad_groups 为已有的搜索广告系列起草广告组：ADM 分析着陆页，按主题将关键字分组，并为每组生成自适应搜索广告。它不改动 Google Ads，需要读写密钥与付费套餐。起草在后台执行，调用会立即返回 draft_id。

草稿的使用方式：

1. 调用 draft_ad_groups，之后每隔 poll_after_seconds 秒调用一次 get_ad_group_draft，直到 status 为 done 或 failed。起草通常在 1 至 3 分钟内完成。
2. 把 ad_groups 原样传给 add_ad_groups 并预览。组名已包含前缀与语言标签。
3. primary_ad_group 是关键字最多的那个组。暂停状态的关键字、起草结果中未分组的关键字，以及分组超过 20 个时超出部分的关键字，都放在这个组里。手写广告（add_ads）与广告组否定关键字（add_keywords）只加到这个组。

草稿保留 24 小时。每次起草会执行多次 AI 调用，每个 ADM 账号每小时最多发起 60 次。草稿处于 pending 或 running 时，不要用相同输入重复调用。

图片上传

add_images 关联的是事先上传到 ADM 的图片。每个文件以 multipart/form-data 格式放在 file 字段中上传，使用同一个 API 密钥：

curl -F [email protected] -H "Authorization: Bearer adm_xxx" https://app.adm.cc/mcp/uploads

PowerShell 中请用 curl.exe，参数相同。

上传接受不超过 5120 KB 的 JPG 与 PNG 文件，格式按文件内容识别，与文件名无关。随后由 add_images 的预览校验尺寸：方形 1:1 不小于 300×300，或横向 1.91:1 不小于 600×314，宽高比允许 1% 误差。上传需要读写密钥与付费套餐，每次上传计为一次写入。

响应（HTTP 200）：

{
  "upload_id": "upl_...",
  "width": 1200,
  "height": 628,
  "bytes": 184320,
  "sha256": "...",
  "content_type": "image/jpeg",
  "expires_at": "2026-10-01T09:30:00+00:00"
}

upload_id 有效期 24 小时（见 expires_at），且只对上传它的 ADM 账号有效。过期后 add_images 返回 not_found，需重新上传文件，并用新的 upload_id 重新预览。

出错时返回 {"error": {...}}，包含 code、message、field_path、fix 与 request_id：

Google 只为符合条件的账号展示图片素材资源，例如开户满 60 天、近期有搜索广告花费、政策记录良好且不属于敏感行业。不符合条件时，Google 可能拒绝关联，或不展示这些图片。Google 还会按内容对图片去重：账号中已有相同图片时直接复用，已关联到目标的图片标记为 exists。

校验上限

显示宽度中，中日韩文字每字计 2。不接受 emoji。固定位置 pinned_field 取 HEADLINE_1 至 HEADLINE_3、DESCRIPTION_1 与 DESCRIPTION_2。

出价 type 取 MANUAL_CPC、MAXIMIZE_CLICKS、MAXIMIZE_CONVERSIONS、MAXIMIZE_CONVERSION_VALUE、TARGET_CPA、TARGET_ROAS 之一。MANUAL_CPC 必须在系列或每个广告组上设置 max_cpc；MAXIMIZE_CLICKS 下的 max_cpc 为 CPC 上限。network_settings.google_search 必须为 true。

campaign.languages 会被接受但不生效：搜索广告系列创建时不设系列级语言定向。请用广告组的 language 字段记录广告语言。

7. 错误码

错误统一使用以下结构：

{
  "code": "invalid_argument",
  "message": "What went wrong",
  "field_path": "campaign.ad_groups[0].ads[0].headlines[3].text",
  "fix": "How to correct it",
  "retryable": false,
  "retry_after_seconds": null,
  "action_url": null,
  "request_id": "..."
}

密钥缺失或无效时，任何工具执行前都会返回 HTTP 401（unauthorized），见第 4 节的连接排查表。

每次工具调用都在 45 秒内返回。数据量大的查询可以用 campaign_id 缩小范围。

8. 配额

• 每月创建次数与 ADM 网页端创建向导共用，在账单日重置。get_accounts 会显示剩余次数与重置时间。
• 写入次数指带 confirm: true 的调用，每次图片上传也计入；预览不计入。
• AI 起草（draft_ad_groups）单独按小时限额，不计入写入次数。
• 写入需要同时具备读写密钥与有效的付费套餐。

9. 为什么不应自动批准写入工具

部分读取工具返回的是他人写下的文字：搜索字词由看到你广告的任何人输入，广告文字、素材资源文字与名称也可能来自同事或代理商。搜索字词中可能出现看似给 AI 工具的指令。ADM 会把这类内容标注为数据，并要求 AI 工具忽略其中的指令，但无法保证任何 AI 模型每次都遵守这条规则。

写入工具的确认提示，是你看清具体改动的环节，请保留：

• 只自动批准读取工具。在 Claude Code 中只允许 mcp__adm__get_*，不要把 mcp__adm__* 或单个写入工具加入允许列表。
• 连接 ADM 服务器时，不要以关闭确认提示的方式运行 AI 工具。
• 确认前逐项阅读预览，尤其是预算与 set_campaign_status 调用。

10. 轮换密钥

1. 在 API 密钥页面创建新密钥。
2. 替换密钥：更新 ADM_API_KEY，或 AI 工具 MCP 配置中的密钥，然后重启 AI 工具。Claude Code 在添加服务器时保存请求头，因此需执行 claude mcp remove adm 后重新添加（见第 4 节）。
3. 在每台使用旧密钥的电脑上重复第 2 步。
4. 观察旧密钥的「最近使用」时间，不再变化后撤销旧密钥。

请像对待密码一样保管密钥：不要提交到代码仓库，也不要写入项目文件。粘贴到对话中的密钥会保留在对话记录中，对话记录可能被他人看到时请轮换。密钥可能泄露时，请立即撤销。

11. 需在 Google Ads 中手动完成的操作

这些工具只负责创建与添加，除暂停与启用广告系列外，不修改也不删除已有内容。以下操作请直接在 Google Ads 中完成：

• 修改或删除已有的广告、关键字、否定关键字与素材资源
• 修改已有广告系列的预算或出价
• 关闭自动应用建议（「建议」页面中的「自动应用」）
• 设置转化跟踪
• 添加徽标、商家名称、来电与潜在客户表单素材资源
• 设置广告投放时间、设备出价调整与受众群体
• 创建搜索以外类型的广告系列，例如效果最大化广告系列
• 管理结算、完成广告客户验证

12. 更新日志

2026-09-30

• ADM MCP Server 首次发布，契约版本 2026-09-30。
• 9 个读取工具：get_accounts、get_campaigns、get_campaign_setup、get_ads、get_keywords、get_search_terms、get_negative_keywords、get_assets、get_operation。
• 11 个写入工具：create_search_campaign、add_ad_groups、add_keywords、add_account_negative_keywords、create_shared_negative_list、attach_shared_negative_list、add_sitelinks、add_callouts、add_structured_snippets、add_prices、set_campaign_status。
• 按投放计划批量创建广告系列的 ADM Skill adm-google-ads（见第 3 节）。
• 同一契约版本内新增（只增加工具与字段，无破坏性变更）：写入工具 add_ads 与 add_images，AI 起草工具 draft_ad_groups 与 get_ad_group_draft，图片上传端点 POST /mcp/uploads，get_assets 与 get_campaign_setup 返回图片素材资源。Skill 增加 AI 起草与图片两个流程。
• 文档迁至 /docs/google-ads-skill。Skill 增加报表查询、按项目保存的默认账号，以及 Codex、Cursor 与 Windsurf 的接入方式；服务端指令加入同样的默认账号规则。在项目中首次使用时，Skill 会给出可直接复制的提示词建议。