English

适用于 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 账号对接起来。

  • 读取不限套餐:查询报表、搜索字词、关键字、广告与素材资源,以及基于 Google 关键字规划师数据的关键字调研,ADM 的每个套餐都开放,免费版同样在内。
  • 写入需付费套餐:广告系列、广告组、广告、关键字、否定关键字与素材资源的创建,必须持有付费套餐,即 Starter、Professional 或 Enterprise。
  • 托管版 ADM 现阶段的开放范围:读取工具和 AI 起草。写入工具还没放开;要在 Google Ads 里真正建出广告系列,走 ADM 的广告系列创建向导。
  • 改动先给预览:每一项变更都由 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-10-03
  • GitHub 仓库:ownway18/adm-google-ads-skill

1. 三步接入

第 1 步:新建 API 密钥。 先登录 ADM,进入 https://app.adm.cc/apikeys,然后挑选权限:

  • 只读:只能做报表与配置查询,任何套餐都能用,免费版也不例外。
  • 读写:在报表查询之外还能调用写入工具,前提是付费套餐处于有效状态。

密钥明文只在创建时出现一次,关掉对话框之前记得先复制走。

第 2 步:交给 AI 工具安装。 把下面这段提示词复制出来,用你自己的密钥顶替其中的 adm_xxx,再发给 AI 工具。接下来的动作由它照第 5 节执行:连上 ADM MCP Server、把 Skill 文件存到本地、试一次连接。安装完成后,按它给出的提示重启。

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 工具

你要做的事 ADM 工具
选择或切换 Google Ads 账号 get_accounts
查询报表、了解投放效果 get_campaigns、get_ad_groups、get_keywords、get_search_terms、get_ads、get_negative_keywords、find_negative_conflicts、get_paused_summary、get_assets、get_conversion_actions、get_customizers
关键字提示与搜索量 get_keyword_ideas、get_keyword_metrics
按设备(手机、计算机、平板电脑)查看效果 get_device_performance
降低或屏蔽手机、计算机或平板电脑的出价 set_device_bid_adjustments
查看各地区的花费与转化,并调整已定向地域的出价 get_location_performance、set_location_bid_adjustments
只凭预览编号确认一次写入 confirm_preview
按投放计划创建广告系列 create_search_campaign、add_ad_groups、add_keywords、add_ads
否定关键字 add_account_negative_keywords、create_shared_negative_list、attach_shared_negative_list
附加链接、宣传信息、结构化摘要、价格、促销与来电 add_sitelinks、add_callouts、add_structured_snippets、add_prices、add_promotions、add_calls
商家名称 add_business_name
图片素材资源与商家徽标 先调用上传端点 POST https://app.adm.cc/mcp/uploads,再调用 add_images 或 add_business_logo
由 ADM AI 起草广告组 draft_ad_groups、get_ad_group_draft
由 ADM AI 起草新广告系列 draft_campaign、get_campaign_draft,再调用 create_search_campaign
核对创建结果、中断后继续创建 get_campaign_setup、get_operation
启用或暂停广告系列 set_campaign_status
暂停广告系列,或修改名称、日预算、出价或语言 update_campaign
增加或移除定向地域、排除地域 update_campaign_locations
创建、挂载或修改共享出价组合 get_bidding_strategies、create_bidding_strategy、attach_bidding_strategy、update_bidding_strategy
暂停或解除附加信息关联 set_asset_link_status
给广告组改名、暂停、启用或改最高 CPC update_ad_group、set_ad_group_status
修改已有广告的文案 update_ads
启用、暂停或移除广告与关键字 set_ad_status、set_keyword_status
添加或删除否定关键字 add_campaign_negative_keywords、remove_negative_keywords、add_shared_negative_keywords、remove_shared_negative_keywords
用自定义参数、跟踪模板或最终到达网址后缀标记点击来源 set_url_options

每个工具的完整说明和参数清单在第 6 节。

3. 接入后可以这样说

  • 「最近 30 天花钱最多的广告系列是哪个?各自带来多少转化?」
  • 「把过去 14 天花了钱却零转化的搜索字词列出来。」
  • 「为 https://www.example.com/photo-enhancer 查找面向德国的关键字提示,并列出月均搜索量。」
  • 「按 plan.md 建广告系列,先给我看预览,我确认后再动。」
  • 「照 plan.md 里 photo-enhancer 那一节起草广告组。」
  • 「拿 https://www.example.com/photo-enhancer 新建一个搜索广告系列,关键字让 ADM 去探索,先预览,等我确认。」
  • 「把 banner.jpg 当作图片素材资源挂到 photo-enhancer@DE 广告系列上。」
  • 「换到 MySecond 这个广告账号。」
  • 「每个广告系列都加上自定义参数 myname,好让我知道点击出自哪一个系列。」

默认账号

如果有多个 Google Ads 账号连着,Skill 只会问一遍用哪个,答案记在项目目录的 .adm/account.json 里;文件里只写客户 ID 和账号名称,API 密钥不在其中。此后这个项目里的请求都按该账号处理,动手之前会先报出当前账号。账号只有一个时,Skill 不问,直接用。想换账号就说「换到 MySecond 这个广告账号」。万一存下来的账号后来在 ADM 里被断开,Skill 会在下次操作前停住,告诉你该账号已断开,并问用哪个——哪怕只剩一个账号也照样问。

优化账本

每次你批准的改动生效后,Skill 会在项目目录的 .adm/optimization-log.<customer_id>.md 里追加一条带日期的记录:改了什么(名称、ID、改前改后)、本次你定下的规则(例如「保留 10 年品质保证这条标题」),以及之后要复查的事项,每项都写明日期和判断方法。每个账号各用一个文件,切换账号不会混在一起。

下次开始时,Skill 先读账本:到期或已过期的复查项最先列出,并建议当场复查;你定下的规则直接照办,不再重复询问。只看报表、没有写入的会话不改动账本;在第一次批准改动之前,也不会创建账本。文件里没有 API 密钥,可以随时修改或删除。

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

下面这个例子用虚构品牌 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.

第一次调用 create_search_campaign 时不带 confirm。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_* 覆盖 ADM 里所有以 get_ 开头的工具,共 9 个读取工具,再加两个只读 AI 草稿状态的 get_ad_group_draft 和 get_campaign_draft。写入工具千万别放进去(见第 9 节)。draft_ad_groups、draft_campaign 虽然不碰 Google Ads,可每次调用背后是一串 AI 请求,所以也排除在这条规则之外。注册服务器时若起了别的名字,把规则里的 adm 相应换掉。

Codex 用这条命令注册:

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

ADM_API_KEY 由 Codex 在启动时读入。

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 工具,再让它把账号列一遍。Windsurf 的配置文件如果不是那个路径,可以在 MCP 设置里点 View raw config 打开。${env:ADM_API_KEY} 表示从 AI 工具自己进程的环境里取值。Cursor 和 Windsurf 都是 VS Code 系,从程序坞或启动器打开时一样会读 ~/.zshrc / ~/.bashrc 里的变量。变量设好或改过之后,得把 AI 工具彻底退出再开(macOS 按 Cmd+Q,光关窗口程序还活着);不然请求头里没有密钥,服务器只会返回 HTTP 401。

连接排查

现象 原因 处理
HTTP 401 密钥缺失、输错,或首尾带空格 检查 ADM_API_KEY 并重启 AI 工具,或删除服务器配置后按原样粘贴密钥重新添加
HTTP 401 密钥已在 API 密钥页面撤销 创建新密钥并更新配置(见第 10 节)
Windows 上 HTTP 401 请求头中的 PowerShell 变量被单引号包裹,未被展开 改用双引号,或直接把密钥粘贴到命令中
设置环境变量后仍为 HTTP 401 AI 工具在设置变量之前就已启动 完全退出 AI 工具后重新打开(macOS 上按 Cmd+Q);在终端中运行的工具需从新打开的终端启动。仍为 HTTP 401 时,在已设置该变量的终端中启动编辑器,例如 cursor .
HTTP 404 地址错误 地址必须是 https://app.adm.cc/mcp:https、app. 子域名、/mcp 路径
超时或连接被拒绝 公司代理或防火墙拦截 启动 AI 工具前设置 HTTPS_PROXY,或请网络管理员放行 app.adm.cc

一个密钥先前还能用,如今却回 401,多半是被撤销了。每个密钥最近一次被使用的时间,API 密钥页面上都看得到。

5. AI 工具安装步骤(供 AI 工具读取)

这一节的目标读者是 AI 工具,所以用英文写。你只要把第 1 节的第 2 步做完,剩下的它会照本节自己办。

You have been handed an ADM API key by the user; its prefix is adm_. Set ADM up in the order below, and afterwards report what you did.

  1. Register the MCP server for the current user, so every project can reach it. Name it adm; point it at https://app.adm.cc/mcp over Streamable HTTP; send the header Authorization: Bearer <key>. The key belongs in your user-level MCP configuration only — keep it out of project files and out of any git repository. Should an adm server already be configured, overwrite that entry.
AI tool How to add the server
Claude Code Run claude mcp add --transport http --scope user adm https://app.adm.cc/mcp --header "Authorization: Bearer <key>"
Codex In ~/.codex/config.toml add [mcp_servers.adm] with url = "https://app.adm.cc/mcp" and http_headers = { "Authorization" = "Bearer <key>" }
Cursor In ~/.cursor/mcp.json add "adm": { "url": "https://app.adm.cc/mcp", "headers": { "Authorization": "Bearer <key>" } } under mcpServers
Windsurf In ~/.codeium/windsurf/mcp_config.json add "adm": { "serverUrl": "https://app.adm.cc/mcp", "headers": { "Authorization": "Bearer <key>" } } under mcpServers

Leave every other server already present in those files untouched. Under Windows, ~ means the user profile folder.

  1. Store the skill file. Fetch https://adm.cc/docs/google-ads-skill/SKILL.md and place it at adm-google-ads/SKILL.md under the skills directory you consult for all projects; the folder has to be named adm-google-ads. Create any directory that is missing. When that directory is unknown to you, fall back to the project-level one:
AI tool Skill file path
Claude Code ~/.claude/skills/adm-google-ads/SKILL.md
Codex .agents/skills/adm-google-ads/SKILL.md
Cursor .cursor/skills/adm-google-ads/SKILL.md
Windsurf .windsurf/skills/adm-google-ads/SKILL.md
  1. Verify the connection. On the adm server, call get_accounts. If the tool only shows up after a restart, tell the user that.

  2. Report back: the location of the server configuration and of the skill file, whether a restart is required, and which Google Ads accounts were discovered. Once restarted, the user can verify by saying "List my Google Ads accounts".

更新 Skill

版本号写在 Skill 文件的 metadata 里。本地那份太旧时,get_accounts 的响应会带上 skill_update_hint,AI 工具据此提醒你一次。要更新,就把 https://adm.cc/docs/google-ads-skill/SKILL.md 下载下来,盖掉本地的 adm-google-ads/SKILL.md(路径见上文第 2 步),再重启 AI 工具。

6. 工具参考

凡是对某个账号生效的工具,传的都是 get_accounts 给出的 customer_id(形如 123-456-7890);get_operation、get_ad_group_draft、get_campaign_draft 是例外,只要各自的 ID 即可。金额统一按账号币种的主单位表示,写成 5.00 这样,不用 micros。报表参数 days 的取值是 1 到 30 个完整自然日,按账号时区算、今天不计,不传则为 7。列表类工具一页最多返回 limit 行,范围 1 到 200、默认 50,同时给出 next_cursor 供继续翻页。

读取工具

工具 返回内容 主要参数
get_accounts 已连接账号(customer_id、名称、币种、时区)、你的套餐、密钥权限、能否写入、本月剩余创建次数与今日剩余写入次数。传入 skill_version 时还会说明 Skill 文件是否需要更新(skill_update_hint)。应最先调用。 skill_version
get_campaigns 广告系列设置与效果数据,按花费排序。已移除的系列不返回。 days、status(ENABLED 或 PAUSED)、limit、cursor
get_campaign_setup 单个广告系列的配置。include 可选 ad_groups、keywords、ads、assets(默认前三项,不含素材)。带了 ad_groups 时,系列素材留在系列上,广告组素材留在各组上。只传 assets 时两类都返回,广告组素材保留 level 和 ad_group_id。广告含 ad_strength、approval_status、review_status 与 policy_topics。关键字 id 供 set_keyword_status 使用。系列与各广告组上的 device_bid_adjustments 只列出非 0。 campaign_id、include
get_ads 自适应搜索广告的标题、描述、固定位置、每条素材的 performance_label、广告效力与效果数据。text_contains 同时匹配标题和描述。compact 只返回 id 与文案。每条广告带 approval_status、review_status,被 Google 标记时另有 policy_topics(主题、类型、被标记的文字或目标网址)。approval_status 作为过滤条件时只返回该审核结果的广告,例如 DISAPPROVED。 campaign_id、ad_group_id、approval_status、days、text_contains、compact、limit、cursor
get_keywords 关键字(Google 写法)的状态、质量得分、最高 CPC 与效果数据。可用 status、match_type、text_contains 过滤(文字里的引号与方括号会被忽略)。compact 只返回 id、文字、状态、所属系列与广告组。 campaign_id、ad_group_id、days、status、match_type、text_contains、compact、limit、cursor
get_search_terms 触发广告的搜索字词、匹配到的关键字与效果数据。按花费排序,最多返回前 10,000 行(截断时 truncated 为 true)。text_contains 只保留包含该文字的搜索字词。group_by: "search_term" 每个搜索字词返回一行合计,并带 ad_group_count。min_cost 只保留花费不低于该金额(账号币种)的行。 campaign_id、ad_group_id、days、text_contains、group_by、min_cost、limit、cursor
get_negative_keywords 按层级列出否定关键字:账号级、系列级、广告组级与共享列表(含列表 ID 与已挂载的系列)。每条关键字的 id 是供 remove_negative_keywords 使用的条件 ID。 campaign_id
get_assets 附加链接、宣传信息、结构化摘要、价格、图片、促销、来电、商家名称与商家徽标。level 为 customer、campaign 或 ad_group(不传则三级都返回)。还可传 types、asset_ids、link_status、limit、cursor。 campaign_id、level、types、asset_ids、link_status、limit、cursor
get_bidding_strategies 共享出价组合:id、名称、类型、目标 CPA 或 ROAS、CPC 上限,以及挂在每个组合上的广告系列。 无
get_device_performance 按设备(MOBILE、DESKTOP、TABLET)拆开的效果,含转化率、每次转化费用和当前出价调整(0 表示没有调整,-100 表示屏蔽)。仅搜索广告系列。level 为 campaign(默认)或 ad_group。 level、campaign_id、days、limit、cursor
get_location_performance 按用户实际所在地拆开的效果。已定向且出价不是 0 时带 bid_adjustment_percent。location_id 可传给 update_campaign_locations 或 set_location_bid_adjustments。 granularity、campaign_id、days、limit、cursor
get_ad_groups 广告组的状态、所属系列、最高 CPC、出价方式、关键字数与广告数。传 days 时附带各广告组的效果数据,并按花费排序。 campaign_id、status、days、limit、cursor
get_paused_summary 按系列、广告组、关键字、广告统计暂停数量,并列出 id 与名称(每级最多 200 条)。 无
find_negative_conflicts 被否定关键字挡住的正向关键字,标明是哪一级的哪条否定词。可传入尚未添加的 negatives 与 keywords(各最多 50)做预检。 campaign_id、negatives、keywords、limit、cursor
get_conversion_actions 转化操作:名称、状态、类型、类别、是否计入「转化」列、价值设置、计数方式与归因模型。include_metrics 附带账户时区里最近 30 个完整自然日的转化数与转化价值,响应里带 date_range。 include_metrics
get_customizers 广告定制工具属性,以及账户、系列、广告组三级的取值。广告文案用 {CUSTOMIZER.Name:default},长度按默认值计算。 无
get_keyword_ideas 按种子关键字、网页网址或两者,从 Google 关键字规划师获取关键字提示:avg_monthly_searches、competition(LOW、MEDIUM 或 HIGH)、competition_index(0 至 100)及页首出价的低位与高位。按搜索量从高到低排序;每次最多 500 条,Google 还有更多时 truncated 为 true。 keywords(1 至 20 个种子)、url、language(默认 en)、country_codes(最多 10 个,默认 US)、min_monthly_searches、include_monthly、limit、cursor
get_keyword_metrics 查询已有关键字的同类指标。可使用匹配类型写法,引号与方括号会被忽略。Google 会把近似变体(如 car 与 cars)合并为一行,其余写入 close_variants,因此返回行数可能少于 requested_count。 keywords(1 至 200 个)、language、country_codes、include_monthly、limit、cursor
get_operation 某次写入调用的记录结果:pending、completed、partial、failed 或 unknown,以及实际创建的资源。 operation_id

关键字规划师的数据仅覆盖 Google 搜索网络。搜索量为近似值,Google 会将其归入区间。出价以账号币种的主单位表示。无数据的字段直接省略,不填 0;结果中没有出现的关键字表示没有数据,不等于零搜索量。同一账号、同一组参数的结果缓存 24 小时。

写入工具

写入工具一律走两段:先预览。调用时不带 confirm,服务端只做校验、回一份预览,什么都不改;每份预览对应一个 preview_id。你确认之后有两条路——要么调 confirm_preview、参数里只放这个 preview_id,要么在原工具上再调一次,参数一字不改、加上 "confirm": true 和这个 preview_id,限 30 分钟之内。确认时漏了 preview_id,返回 invalid_argument。preview_id 尚未确认、时限已超过 30 分钟,返回 preview_required。确认过的 preview_id 只会把当时的结果还给你,不会再写一次,哪怕已经过了 30 分钟,结果照旧。想再来一遍同样的改动,只能重新预览、确认,然后用新的 preview_id。

工具 作用 主要参数
create_search_campaign 一次创建完整的搜索广告系列:预算、出价、网络、地区、否定关键字、共享列表、广告组、关键字与自适应搜索广告。创建后一律为暂停状态。 campaign(见第 3 节的示例)
add_ad_groups 向已有搜索广告系列添加广告组(含关键字、否定关键字与广告)。除非 status 为 ENABLED,否则创建为暂停。 campaign_id、ad_groups、status
add_keywords 向一个广告组添加关键字、暂停状态的关键字与广告组否定关键字。已存在的关键字标记为 exists。 ad_group_id、keywords、paused_keywords、negative_keywords
add_ads 向已有广告组添加 1 至 3 条自适应搜索广告(结构与 add_ad_groups 中的广告相同,含 path1 与 path2)。每个广告组最多 3 条,暂停的广告也计入。标题与描述都与已有广告相同的,标记为 exists。新广告为启用状态,广告组与系列都启用时,经 Google 审核通过后展示。 ad_group_id、ads
update_ads 原地修改自适应搜索广告,广告 ID 保留。headlines / descriptions 整组替换。headline_replacements / description_replacements({from, to})按原文替换一条并保留固定位置;to 为空则删除。同一条广告里不能和整组替换一起用。预览列出每条广告的改前与改后,并附 diff:新增、删除、固定位置变化与顺序变化的文字。 ads:{ad_id, headlines?, headline_replacements?, descriptions?, description_replacements?, final_url?, path1?, path2?}
add_account_negative_keywords 向账号级否定列表添加否定关键字,对账号下所有搜索广告系列生效,包括正在投放的系列。 keywords(最多 500 个)
create_shared_negative_list 创建共享否定关键字列表,可在同一请求中挂载到广告系列。 name、keywords(最多 1,000 个)、campaign_ids
attach_shared_negative_list 把已有共享列表挂载到广告系列。 shared_list_id、campaign_ids
add_sitelinks 添加附加链接:链接文字不超过 25,两行说明可选、每行不超过 35(要么都填,要么都不填),以及最终到达网址。 level、sitelinks、campaign_ids 或 ad_group_ids
add_callouts 添加宣传信息,每条不超过 25。 level、callouts、campaign_ids 或 ad_group_ids
add_structured_snippets 添加结构化摘要。传了 language 时,header 必须是该语言的官方译名(如德文 Marken、丹麦文 Typer),否则预览直接报错并给出可用列表。不传语言时,任一官方译名都接受;未收录的语言仍只警告,确认时由 Google 校验。3 至 10 个值,每个不超过 25。 level、snippets(header、values、language)、campaign_ids 或 ad_group_ids
add_prices 添加价格素材资源,3 至 8 个价格项。language_code 只能是 de、en、es、es-419、fr、it、ja、nl、pl、pt-BR、pt-PT、ru、sv。币种必须是价格素材支持的(含 USD、EUR、GBP 等,不含 DKK、NOK)。 level、prices、campaign_ids 或 ad_group_ids
add_promotions 添加促销素材资源。promotion_target 不超过 20 个字符。percent_off(30 即 30% 折扣)与 money_amount_off(须带 currency)二选一,金额按标准货币单位。language_code 与 final_url 必填。可选:occasion、discount_modifier(UP_TO)、promotion_code 与 orders_over_amount(同样须带 currency)二选一,以及 start_date / end_date(yyyy-MM-dd)。 level、promotions、campaign_ids 或 ad_group_ids
add_calls 添加来电素材资源:country_code(2 位字母)与 phone_number。call_conversion_reporting_state 可选;取 USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION 时可传 get_conversion_actions 返回的 call_conversion_action_id(不传则使用 Google 默认的来电转化操作)。 level、calls、campaign_ids 或 ad_group_ids
add_business_name 添加商家名称素材资源,不超过 25 个字符。能否展示取决于 Google 的资格审核,预览会列出审核条件。 level(customer 或 campaign)、business_name、campaign_ids
add_business_logo 用已上传的文件添加商家徽标(见下文「图片上传」):方形 1:1,不小于 128×128。能否展示取决于 Google 的资格审核,预览会列出审核条件。 level(customer 或 campaign)、logos(upload_id,name 可选)、campaign_ids
add_images 用已上传的文件向搜索广告系列或广告组添加图片素材资源(见下文「图片上传」),按目标分别返回结果。 level(campaign 或 ad_group)、images(upload_id,name 可选)、campaign_ids 或 ad_group_ids
set_campaign_status 暂停或启用最多 50 个广告系列。传 campaign_id 与 status,或传 campaigns。预览列出每个系列的日预算,以及即将新启用部分的日预算合计与月估算。手动 CPC 且广告组最高 CPC 仍是占位价(不超过 0.05)时会警告。 campaign_id 与 status,或 campaigns:{campaign_id, status}
confirm_preview 执行用户已批准的预览。只传 preview_id。服务端重放当时存下的参数,哈希与幂等账本与原工具确认相同。 preview_id
set_location_bid_adjustments 调整系列上已经定向的地域的出价。-90 到 900,0 表示清除。不新增也不移除地域。智能出价会忽略这些调整。 items:{campaign_id, location_id, adjustment_percent}
set_customizer_values 广告定制工具。属性不存在时按 TEXT、NUMBER、PRICE 或 PERCENT 创建,并在账户、系列或广告组写入取值。 items:{name, type, value, level, campaign_id, ad_group_id}
update_campaign 一次原子完成:改名、暂停,和/或设置日预算、出价或语言。status 只接受 PAUSED。共享预算会被拒绝。系列正在使用出价组合时传入 bidding 会把它摘下来:系列改用自己的出价,预览会写明离开的组合名称。bidding.max_cpc 只作尽可能争取更多点击的出价上限;MANUAL_CPC 会拒绝它,广告组出价用 update_ad_group 设置。搜索广告系列不能设置语言(Google 于 2026 年 9 月移除);预览会说明,且该次调用中的其他字段也不会改动。预算预览会给出新旧日预算与月估算。 campaign_id,name、status(PAUSED)、daily_budget、bidding、languages 至少传一个
update_campaign_locations 在一个广告系列上增加或移除定向地域和排除地域,一次原子完成。每项是 get_campaign_setup 或 get_location_performance 里的 {location_id},或 {country_code}。删掉排除或加上定向会扩大投放范围、可能增加花费;系列为 ENABLED 时预览会写明。删掉最后一个定向地域后,该系列面向除剩余排除以外的所有地域。不支持半径定向。 campaign_id,add_targets、remove_targets、add_exclusions、remove_exclusions 至少传一个
set_device_bid_adjustments 设置搜索广告系列和广告组的设备出价调整(最多 50 条),一次全部生效或全部不改。device 为 MOBILE、DESKTOP 或 TABLET。-100 屏蔽该设备。-90 到 900 降低或提高出价。0 清除调整(广告组会改回继承系列)。广告组的调整覆盖系列。尽可能提高转化次数、目标广告支出回报率和尽可能提高转化价值会忽略 -100 以外的值。目标每次转化费用会按该设备改目标 CPA。把三种设备都设为 -100 会被拒绝。 items:{level, campaign_id, ad_group_id, device, adjustment_percent}
set_asset_link_status 暂停、启用或解除附加信息关联(最多 300 条)。REMOVED 只解除关联且不可撤销,素材本身保留。同一素材在该层级挂了多个字段类型时,每条关联都会改。账户级附加链接在已有系列级附加链接的系列上仍可能展示,预览会列出所有可能受影响的系列。其他类型则列出没有自己同类型素材的系列。结果按条返回。 items:{level, asset_id, campaign_id, ad_group_id, status}。level 为 customer、campaign 或 ad_group。status 为 ENABLED、PAUSED 或 REMOVED
create_bidding_strategy 创建一个共享出价组合(TARGET_CPA、TARGET_ROAS、MAXIMIZE_CLICKS、MAXIMIZE_CONVERSIONS、MAXIMIZE_CONVERSION_VALUE)。拒绝 MANUAL_CPC。max_cpc 是可选的 CPC 上限。可选 campaign_ids(最多 50 个)在同一次原子改动里挂上。ENABLED 的系列会进入学习期。 name、bidding、campaign_ids
attach_bidding_strategy 把广告系列挂到已有出价组合(最多 50 个)。会替换每个系列自己的出价。已挂在别的组合上的系列会离开那个组合。结果按系列返回。 strategy_id、campaign_ids
update_bidding_strategy 给出价组合改名,和/或修改目标 CPA、目标 ROAS 或 CPC 上限。类型不能改。新目标作用于挂在该组合上的每一个系列,预览会列出它们。 strategy_id,name、bidding 至少传一个
update_ad_group 一次原子完成:改名、设为 PAUSED 或 ENABLED,和/或设置 max_cpc。不能移除广告组。max_cpc 只在广告系列使用 MANUAL_CPC 时生效,否则预览会说明。广告组一旦启用,只要所属广告系列已启用就会产生花费。 ad_group_id,name、status(ENABLED 或 PAUSED)、max_cpc 至少传一个
set_ad_status 把广告设为 ENABLED、PAUSED 或 REMOVED(最多 100 条)。REMOVED 不可恢复。暂停的广告仍计入广告组最多 3 条自适应搜索广告的上限。不改变广告系列状态。结果按条返回。 ads:{ad_group_id, ad_id, status}
set_keyword_status 把正向关键字设为 ENABLED、PAUSED 或 REMOVED(最多 300 条)。否定关键字会被拒绝。REMOVED 不可恢复。不改变广告系列状态。结果按条返回。 keywords:{ad_group_id, criterion_id, status}
set_ad_group_status 把广告组设为 ENABLED、PAUSED 或 REMOVED(最多 50 个)。REMOVED 不可恢复。不改变广告系列状态。广告组设为 ENABLED 后,只有所属广告系列已经启用才会投放。 ad_groups:{ad_group_id, status}
add_campaign_negative_keywords 给一个广告系列添加否定关键字(Google 写法,最多 500 条)。对系列里现有和以后新建的广告组都生效。已有的返回 exists。 campaign_id、keywords
remove_negative_keywords 删除否定关键字(最多 300 条)。只删除否定关键字。地域条件会被拒绝(用 update_campaign_locations);语言条件会被拒绝(用 update_campaign)。REMOVED 不可恢复。 items:{level, parent_id, criterion_id}。level 为 account、campaign、ad_group 或 shared_list。account 的 parent_id 可省略
add_shared_negative_keywords 往已有共享否定列表追加关键字(最多 500 条)。不新建列表。账号级列表会被拒绝。预览会列出该列表已挂载的广告系列。 shared_list_id、keywords
remove_shared_negative_keywords 按条件 ID 从已有共享列表删除关键字(最多 300 条)。REMOVED 不可恢复。 shared_list_id、criterion_ids
set_url_options 给广告系列、广告组或广告设置自定义参数、跟踪模板和最终到达网址后缀。自定义参数按 key 合并(value 传空字符串即删除该 key)。在这里设置跟踪模板会盖掉该目标上的账号级跟踪模板。不改出价、预算或状态。 level(campaign、ad_group 或 ad),targets(最多 20 个:id、custom_parameters、tracking_template、final_url_suffix)

素材资源类工具的 level 是 customer(代表所有系列)、campaign 或 ad_group;其中 add_images 认 campaign 和 ad_group 两种,add_business_name、add_business_logo 只认 customer 和 campaign。set_url_options 认的是 campaign、ad_group、ad。素材资源类工具单次上限为 20 项、20 个目标;素材一旦加到正在投放的系列上,要等 Google 审核通过才展示。

用自定义参数看出点击来自哪个广告系列

账号级跟踪模板已经设好时,只需给广告系列、广告组或广告挂上自定义参数,用不着把模板逐系列复制一遍。像 {lpurl}?utm_campaign={_myname}&utm_term={keyword}&utm_ag={_groupname}&utm_ad={_adname} 这样的模板,其中的 {_myname} 就是从广告系列那一层读的。真正存下来的参数名是 myname,不带下划线;myname、_myname、{_myname} 三种写法指向同一个 key。_groupname 放在广告组上、_adname 放在广告上,路子一样。

{
  "customer_id": "123-456-7890",
  "level": "campaign",
  "targets": [
    { "id": 111, "custom_parameters": [{ "key": "myname", "value": "s-en-us" }] }
  ]
}

这个系列上原有的其它自定义参数不受影响,仍会留着。想去掉某个 key,把它的 value 写成 "" 就行。tracking_template 与 final_url_suffix 不传等于保持原样,传 "" 则是清空。在该目标上另设跟踪模板,会把它继承的账号级模板顶掉,这一点预览里会标出来。流程还是先预览,拿到 preview_id 再确认。要核对结果就用 get_campaign_setup 看 url_options,广告那边在 get_ads 里也能看到。整个调用要么全成,要么一条都不落。动过广告的网址选项,这条广告有可能要重新过审。

AI 起草广告组

draft_ad_groups 用来给一个现成的搜索系列起草广告组:ADM 读着陆页,按主题把关键字归类,再给每一类配上自适应搜索广告。整个过程不动 Google Ads,前提是有读写密钥和付费套餐。起草在后台跑,调用立刻返回 draft_id。

工具 作用 主要参数
draft_ad_groups 发起起草,返回 draft_id、status 与 poll_after_seconds。 campaign_id、landing_page_url、keywords(1 至 200 个)、language、paused_keywords、group_name_prefix(不超过 100 个字符)、ads_per_group(1 至 3,默认 1)
get_ad_group_draft 草稿状态:pending、running、done 或 failed。完成时返回 ad_groups、primary_ad_group 与 warnings;失败时返回 error。 draft_id

草稿拿到之后怎么用:

  1. 先调 draft_ad_groups;随后按 poll_after_seconds 给的间隔反复调 get_ad_group_draft,等到 status 变成 done 或 failed 为止。一般 1 到 3 分钟就有结果。
  2. 把 ad_groups 原封不动交给 add_ad_groups,走一次预览。若手里没有 add_ad_groups 这个工具,或者 can_write 是 false,草稿本身就是交付物:把广告组方案直接给用户。组名里前缀和语言标签都已经带上了。
  3. 关键字最多的那个组就是 primary_ad_group。几种关键字会被塞进这里:处于暂停状态的、起草时没能归类的,以及分组数超过 20 时多出来的那些。手写的广告(走 add_ads)和广告组级否定关键字(走 add_keywords)也只会落到这个组。

草稿的寿命是 24 小时。一次起草背后是好几轮 AI 调用,所以每个 ADM 账号每小时最多发起 60 次,这个额度与 draft_campaign 一起算。草稿还是 pending 或 running 期间,不要拿同样的输入再发一次。

AI 起草新广告系列

draft_campaign 则从一个着陆页起步,起草全新的搜索系列:ADM 读页面内容,自己去探关键字、或者用你给的关键字,在可用时参考 Google 关键字规划师的搜索量,按主题分组,逐组生成自适应搜索广告,全程不碰 Google Ads。跑完后把 campaign 原样交给 create_search_campaign,记得先预览。同样要读写密钥与付费套餐,每小时额度与 draft_ad_groups 共用一个池子。至于每月创建次数,要等 create_search_campaign 真正执行时才扣、并由它再校验一遍。

工具 作用 主要参数
draft_campaign 发起起草,返回 draft_id、status、poll_after_seconds 与 explore_keywords。 landing_page_url。可选:keywords(0 至 200 个;不传则探索)、explore_keywords(传了关键字时默认 false;没传关键字时忽略,一律探索)、language(默认 en)、country_code(默认 US)、daily_budget、bidding(默认 MAXIMIZE_CONVERSIONS)、campaign_name、business_goal(SALES、LEADS 或 TRAFFIC,默认 SALES,只引导 AI)、ads_per_group(1 至 3,默认 1)
get_campaign_draft 草稿状态:pending、running、done 或 failed。完成时返回 campaign、missing_fields、warnings、strategy_notes 与 keyword_planner_used;使用了关键字规划师数据时另有 keyword_metrics(每个关键字的 text、avg_monthly_searches、competition,可选 close_variants)。失败时返回 error。 draft_id

新系列草稿的用法:

  1. 调 draft_campaign。keywords 不传,ADM 会照着陆页自己去探;传了 keywords,就只认这一批。若同时把 explore_keywords 置为 true,这批关键字当种子用,ADM 在它们之外再补。之后按 poll_after_seconds 的间隔调 get_campaign_draft,直到 status 显示 done 或 failed。一般 1 到 3 分钟结束。草稿还是 pending 或 running 时,别拿相同输入再发一次。
  2. 状态为 failed,把 error 的内容讲给用户听,重新起草要等用户点头。状态为 done,则把系列名、广告组、warnings 和 strategy_notes 一并摆给用户看。
  3. 展示关键字时附上 keyword_metrics 中的月均搜索量,并注明对应的语言与国家(即草稿所用的语言与国家)。keyword_metrics 中没有的关键字表示没有数据,不等于零搜索量。keyword_planner_used 为 false 时,说明本次草稿没有搜索量数据;之后可用 get_keyword_metrics 核对关键字。删减或增加关键字须经用户同意。页首出价区间仅作预算参考,不代用户确定金额。
  4. missing_fields 不为空,就在创建之前一条一条问用户。没传 daily_budget 时,campaign.daily_budget 保持空缺,别自己拍一个数字;用户给了答案再填回 campaign。
  5. 除补填的字段和用户批准的关键字改动外,把 campaign 原样送去 create_search_campaign 预览。手里没有 create_search_campaign 这个工具、或 can_write 为 false 时,草稿就是终点:把方案交出去,让用户在 ADM 网页端自己建。草稿的投放范围仅限 Google 搜索,地区取自 country_code(默认 US),出价按传入的策略走(默认是尽可能提高转化次数)。用户确认之后,带着 preview_id 执行。新系列落地即暂停。
  6. 最后用 get_campaign_setup 对一遍。

草稿留存 24 小时。draft_ad_groups 产出的 draft_id 拿去调 get_campaign_draft 读不到,反过来也一样——两类草稿各读各的。

图片上传

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,其余参数照旧。

可上传的文件是 JPG 和 PNG,大小不超过 5120 KB;真实格式靠内容判定,文件名不作数。尺寸由 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:

HTTP 状态码 code 原因
400 invalid_argument 请求不是 multipart/form-data、缺少 file 字段,或文件为空
401 unauthorized API 密钥缺失或无效
403 permission_denied 密钥为只读,或当前套餐不含写入权限
404 无 地址错误(端点是 app. 子域名下的 POST https://app.adm.cc/mcp/uploads),或托管版 ADM 暂未开放上传
413 invalid_argument 文件超过 5120 KB
415 invalid_argument 文件不是 JPG 或 PNG 图片
429 quota_exceeded 已达到每日安全上限(UTC)

图片素材资源并非对所有账号都展示,Google 有资格门槛,比如账号开满 60 天、近期在搜索广告上有花费、政策记录干净,且不属于敏感行业。达不到这些条件,Google 可能不接受关联,也可能不展示图片。另外 Google 会按内容给图片去重:账号里已有同一张图就直接复用,已经挂到该目标上的则标成 exists。

校验上限

项目 上限
每次调用的广告组数 20
每个广告组的广告数 3
关键字 每个广告组 300 个,每次调用 2,000 个;每个不超过 80 个字符、10 个词
否定关键字 每个列表或系列 1,000 个
地区 每个系列 50 个;每项为 country_code(ISO 3166-1 两位字母代码)或 location_id 二选一;至少一项为定位(非排除)
每次 create_search_campaign 调用可挂载的共享列表 20
标题 每条广告 3 至 15 个,显示宽度不超过 30
描述 每条广告 2 至 4 条,显示宽度不超过 90
显示路径 path1 与 path2,显示宽度各不超过 15
名称 不超过 255 个字符
图片 JPG 或 PNG,不超过 5120 KB;1:1 不小于 300×300,或 1.91:1 不小于 600×314(允许 1% 误差)
AI 起草 每次 0 至 200 个关键字(新系列草稿可以不传关键字),每组 1 至 3 条广告

算显示宽度时,中日韩字符按 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": "..."
}
错误码 含义 处理
invalid_argument 字段缺失、超出范围或过长 按 field_path 修正所有列出的字段后重新预览
account_not_found 该 customer_id 未连接到你的 ADM 账号 使用 get_accounts 返回的 customer_id,或先在 ADM 中连接该账号
not_found 广告系列、广告组、列表或操作记录不存在 用读取工具重新查询 ID
permission_denied 密钥为只读,或当前套餐不含写入权限 创建读写密钥,或升级套餐(见 action_url)
quota_exceeded 当前套餐本月创建次数已用完,或达到每日安全上限 升级套餐(每月创建次数),或等待错误中给出的重置时间
preview_required confirm: true 或 confirm_preview 用了尚未确认、且 30 分钟内没有缓存的 preview_id 重新预览、取得确认后,带新的 preview_id 执行。这个 preview_id 如果已经确认过,再调 confirm_preview 会返回当时的结果
conflict 已存在同名但内容不同的资源 先查看已有资源,不要改名重建
busy 该 Google Ads 账户已有另一个写入在执行 等待 retry_after_seconds 后重试
reauth_required ADM 的 Google 授权已过期 在 ADM 中重新连接 Google Ads(见 action_url)
google_ads_error Google Ads 拒绝了改动(政策或校验) 阅读 message 中的 Google 原因后调整
result_unknown 调用超时或中断,结果未知 先调用 get_operation 或 get_campaign_setup;确认未生效时重新预览,取得确认后带新的 preview_id 执行
internal 服务器内部错误 重试一次;持续出现时携带 request_id 联系客服

密钥没带或者不对,任何工具都不会被执行,直接回 HTTP 401(unauthorized);排查办法见第 4 节那张连接排查表。

工具调用一律在 45 秒内返回。查询命中数据太多时,用 campaign_id 把范围收窄。

8. 配额

配额 Free Starter Professional Enterprise
读取工具 可用 可用 可用 可用
写入工具 不可用 可用 可用 可用
每月创建广告系列次数 1(仅限网页端) 10 30 100
每日写入次数(UTC) 不可用 3,000 3,000 3,000
每小时 AI 起草次数 不可用 60 60 60
  • 每月创建次数的额度与 ADM 网页端向导共用一份,账单日归零。剩余多少、何时重置,get_accounts 都会告诉你。次数耗尽时,错误信息里会同时列出你当前套餐的每月次数和更高一档的数字;完成升级,限制当场解除。
  • 计入写入次数的只有带 confirm: true 的调用,图片每上传一次同样算一次;预览则不算。
  • 那道每日上限(管的是写入次数、写入条目、预览条目和 Google Ads 查询数)只为拦住失控的自动化,门限远高于正常用量,三个付费套餐一视同仁,每天 UTC 0 点重置。
  • AI 起草(draft_ad_groups、draft_campaign)共用同一个每小时限额,且不进写入次数的账。draft_campaign 自己不占每月创建次数,占的是 create_search_campaign。
  • 想写入,读写密钥和有效付费套餐缺一不可。

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

有些读取工具返回的文字,其实是他人写下的:搜索字词来自每一个看到你广告的人,广告文案、素材文案、各种名称也可能出自同事或代理商之手。搜索字词里完全可能出现长得像给 AI 工具的指令。ADM 会把这类内容标记成数据,并要求 AI 工具不去执行其中的指令,但无法保证每个模型每次都遵守。

写入工具那道确认提示,正是你逐个看清改动的环节,请保留:

  • 自动批准的范围只给读取工具。Claude Code 里允许 mcp__adm__get_* 就够了,别放 mcp__adm__*,也别单独放某个写入工具。
  • 接 ADM 服务器时,不要用那种关掉所有确认提示的方式启动 AI 工具。
  • 确认之前,预览要一项一项读,预算要看,update_ads 要看(广告文案一改就得重新送审),那些把状态置为 ENABLED 的调用尤其要看(set_campaign_status、update_ad_group、set_ad_group_status、set_ad_status、set_keyword_status)。启用广告系列这件事,update_campaign 做不到。REMOVED 一旦执行无法回头。

10. 轮换密钥

  1. 先到 API 密钥页面建一个新密钥。
  2. 把旧密钥替换掉:改 ADM_API_KEY,或者改 AI 工具 MCP 配置里那个密钥,之后重启 AI 工具。Claude Code 的请求头是添加服务器那一刻存下的,所以得先 claude mcp remove adm,再按第 4 节重新添加。
  3. 凡是还在用旧密钥的电脑,第 2 步都要重做一遍。
  4. 盯一下旧密钥的「最近使用」时间,等到它不再变动,再把旧密钥撤销。

密钥要当密码对待:既不能提交进代码仓库,也不能写进项目文件。凡是粘进对话的密钥都会留在记录里,一旦这份记录可能外泄,就该轮换。判断有泄露风险时,立刻撤销。

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

工具能做的事集中在这里:创建与添加;此外还能暂停广告系列,改它的名称、日预算、出价,改语言(搜索广告系列不在其列),增删地域,设置设备出价调整(屏蔽手机也算在内),建立、挂载、调整共享出价组合,给广告组改名、暂停、启用、改最高 CPC 或移除,启用、暂停、移除广告与正向关键字,就地修改现有自适应搜索广告的标题、描述、最终到达网址与展示路径,增删否定关键字,暂停或解除附加信息关联,以及在系列、广告组或广告层面设置网址选项(自定义参数、跟踪模板、最终到达网址后缀)。唯一能启用广告系列的工具是 set_campaign_status。一旦 REMOVED 就无法恢复。下面这些事请回到 Google Ads 里做:

  • 把素材库里没用上的素材删掉(只是解除关联的话用 set_asset_link_status)
  • 给搜索广告系列设语言定向(该能力已被 Google 在 2026 年 9 月移除,搜索广告系列对全部语言开放)
  • 关掉建议的自动应用(位置在「建议」页面里的「自动应用」)
  • 配置转化跟踪
  • 添加潜在客户表单、商务消息、移动应用、地址这几类素材资源
  • 设定广告投放时间,以及受众群体
  • 创建搜索之外的系列类型,比如效果最大化广告系列
  • 处理结算事宜,完成广告客户验证

12. 更新日志

2026-11-13

  • 新增读取工具(无破坏性变更):get_keyword_ideas(按种子关键字、网页网址或两者获取关键字提示)与 get_keyword_metrics(查询已有关键字的搜索量、竞争程度与页首出价区间)。两者均基于 Google 关键字规划师数据,所有套餐可用,包括免费版。
  • draft_campaign 起草时使用 Google 关键字规划师数据;数据不可用时照常起草。get_campaign_draft 新增 keyword_planner_used 与 keyword_metrics,campaign 本身不变。契约版本仍为 2026-10-03。
  • Skill 版本 2026-11-13:展示草稿关键字时附上搜索量并注明语言与国家,关键字改动须经你批准。更新方法见更新 Skill。

2026-11-11

  • Skill 版本 2026-11-11:新增按账号分开的优化账本 .adm/optimization-log.<customer_id>.md。每次批准的改动生效后,Skill 记录改了什么、你定下的规则和到期要复查的事项;下次会话先读账本,列出到期的复查项。MCP 工具没有变化;怎么更新见更新 Skill。

2026-10-13

  • get_ads 现在给每条广告带上 approval_status、review_status、policy_topics 三个字段;同时多了一个可用作筛选的 approval_status 参数。get_campaign_setup 返回的广告也一并带上这三项。
  • get_ads、get_keywords、get_search_terms 三个工具都支持传 ad_group_id 了。
  • get_ad_groups 多了一个 days 参数;传了它,每个广告组的效果数据也会一并给出。
  • get_search_terms 增加 group_by: "search_term",按搜索字词各出一行合计;另增加 min_cost。
  • get_keywords 增加了 compact;用 text_contains 时,文字中带的引号和方括号会被忽略。
  • update_ads 的预览现在逐条广告带上 diff。
  • 上述改动全是可选项,不构成破坏性变更,契约版本停留在 2026-10-03。Skill 文件的版本是 2026-10-13;怎么更新见更新 Skill。

2026-10-12

  • 报表类工具的 days 现在接受 1 到 30 之间的任意整数,不构成破坏性变更,契约版本仍是 2026-10-03。
  • get_search_terms 多了 text_contains,只把含该文字的搜索字词返回给你。
  • Skill 文件里多了一节「Optimizing an account」,用于让 AI 工具对账号做优化。Skill 文件版本升到 2026-10-12,更新方式见更新 Skill。

2026-10-08

  • 托管版 ADM 开放了读取工具和 AI 起草(draft_campaign、draft_ad_groups)。写入工具尚未开放;在写入不可用的环境里,起草产出以投放计划交付,不会被建到 Google Ads 上。
  • get_accounts 可以收 skill_version 了,返回里则多了 skill_latest_version、skill_update_hint、upgrade_hint、upgrade_url;纯属加字段,无破坏性变更,契约版本保持 2026-10-03。Skill 文件版本为 2026-10-08,更新方法见更新 Skill。

2026-10-05

  • 新增工具(仅新增,无破坏性变更):add_promotions、add_calls、add_business_name、add_business_logo。get_assets 的 types 取值里补了 promotion、call、business_name、business_logo;这几类的关联可由 set_asset_link_status 暂停、启用或解除。

2026-10-04

  • 新增一批工具:get_ad_groups、get_paused_summary、find_negative_conflicts、get_conversion_actions、get_customizers、confirm_preview、set_location_bid_adjustments、set_customizer_values。get_campaigns 的返回里出现了目标 CPA、目标 ROAS 与组合出价。get_assets 支持用 level、types、asset_ids、link_status 筛选,翻页走 limit / cursor。get_keywords 支持按 status、match_type、text_contains 筛选。get_ads 收了 text_contains 和 compact,每条标题与描述都附 performance_label。对于已定向的地域,get_location_performance 会给出 bid_adjustment_percent。
  • 有行为变化:get_campaign_setup 默认不返回素材了,想要就在 include 中带上 assets。广告组、关键字、广告仍默认包含。广告对象里带 ad_strength。
  • set_campaign_status 单次上限 50 个系列,预览里会把尚未启用的系列日预算加总。启用手动 CPC 的系列时,若广告组最高 CPC 还是不超过 0.05 的占位值,预览会给出警告。update_ads 支持 headline_replacements 和 description_replacements,按原文替换、固定位置不变。add_prices 在预览阶段就会拒掉不受支持的语言与币种。add_structured_snippets 一旦你指定语言,表头就得符合该语言的官方译名表,否则校验不过。关键字写入的预览里带 campaign_name 与 ad_group_name。用户批准之后,confirm_preview 仅凭 preview_id 就能执行。
  • 新增工具(仅新增,无破坏性变更):get_device_performance、set_device_bid_adjustments、get_location_performance。get_campaign_setup 的返回里现在有系列和每个广告组的 device_bid_adjustments。要做地区排除,还是走 update_campaign_locations。
  • 新增工具(仅新增,无破坏性变更):update_campaign_locations、set_asset_link_status、get_bidding_strategies、create_bidding_strategy、attach_bidding_strategy、update_bidding_strategy。
  • update_campaign 不再把组合出价拒之门外。传了 bidding,系列就会从原组合上摘下来,预览中会写明它离开的是哪个组合。

2026-10-03

  • 契约版本提到 2026-10-03。破坏性变更在这里:update_campaign 的 status 现在只认 PAUSED。要让系列跑起来,只有 set_campaign_status 一条路,而且必须是用户明确要求。REMOVED 之后不可恢复。
  • 新增工具:set_ad_status、set_keyword_status、set_ad_group_status、add_campaign_negative_keywords、remove_negative_keywords、add_shared_negative_keywords、remove_shared_negative_keywords。批量调用的结果逐条给出,失败的那条不会把已经成功的条目回滚。
  • 新增 update_ads(仅新增工具,无破坏性变更,契约版本仍是 2026-10-03):自适应搜索广告可以就地修改。广告 ID 和历史效果数据都留着。别用「先移除、再补一条新的」这种替代做法。
  • update_campaign 添了 daily_budget(共享预算一律拒绝)、bidding(组合出价策略同样拒绝)和 languages(空数组代表全部语言;搜索广告系列会被拒,而且这次调用里的其它字段也一并不会生效)。update_ad_group 添了 max_cpc。get_campaign_setup 返回的关键字里现在有 id,也就是条件 ID。
  • 在同一契约版本 2026-09-30 里补入(仅新增工具,无破坏性变更):draft_campaign 与 get_campaign_draft。ADM 照着陆页起草一个全新的搜索系列,关键字探索、分组、自适应搜索广告都涵盖。草稿完成后,把 campaign 交给 create_search_campaign。每小时的起草额度与 draft_ad_groups 共用。
  • 同一契约版本 2026-09-30 内补入(仅新增工具,无破坏性变更):写入工具 update_campaign 与 update_ad_group。改名、暂停、启用这些动作可以在一次原子调用里对系列或广告组完成,比如顺手在名字里写清停投原因。set_campaign_status 维持原样。
  • 同一契约版本 2026-09-30 内补入(仅新增工具与字段,无破坏性变更):写入工具 set_url_options。有了它,可以在系列、广告组或广告上挂自定义参数(按 key 合并)、跟踪模板、最终到达网址后缀,账号级跟踪模板从此能分辨点击出自哪一层。get_campaign_setup 和 get_ads 只要这三项里有一项带值,就会返回 url_options。

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 会递上一段可直接复制的提示词。

Our site uses cookies. By continuing to use our site, you agree to the use of cookies. For more information about the use of cookies on our website, please see our Cookie Policy.