适用于 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.
- Register the MCP server for the current user, so every project can reach it. Name it
adm; point it athttps://app.adm.cc/mcpover Streamable HTTP; send the headerAuthorization: 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 anadmserver 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.
- Store the skill file. Fetch
https://adm.cc/docs/google-ads-skill/SKILL.mdand place it atadm-google-ads/SKILL.mdunder the skills directory you consult for all projects; the folder has to be namedadm-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 |
Verify the connection. On the
admserver, callget_accounts. If the tool only shows up after a restart, tell the user that.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 |
草稿拿到之后怎么用:
- 先调
draft_ad_groups;随后按poll_after_seconds给的间隔反复调get_ad_group_draft,等到status变成done或failed为止。一般 1 到 3 分钟就有结果。 - 把
ad_groups原封不动交给add_ad_groups,走一次预览。若手里没有add_ad_groups这个工具,或者can_write是 false,草稿本身就是交付物:把广告组方案直接给用户。组名里前缀和语言标签都已经带上了。 - 关键字最多的那个组就是
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 |
新系列草稿的用法:
- 调
draft_campaign。keywords不传,ADM 会照着陆页自己去探;传了keywords,就只认这一批。若同时把explore_keywords置为 true,这批关键字当种子用,ADM 在它们之外再补。之后按poll_after_seconds的间隔调get_campaign_draft,直到status显示done或failed。一般 1 到 3 分钟结束。草稿还是 pending 或 running 时,别拿相同输入再发一次。 - 状态为
failed,把error的内容讲给用户听,重新起草要等用户点头。状态为done,则把系列名、广告组、warnings和strategy_notes一并摆给用户看。 - 展示关键字时附上
keyword_metrics中的月均搜索量,并注明对应的语言与国家(即草稿所用的语言与国家)。keyword_metrics中没有的关键字表示没有数据,不等于零搜索量。keyword_planner_used为 false 时,说明本次草稿没有搜索量数据;之后可用get_keyword_metrics核对关键字。删减或增加关键字须经用户同意。页首出价区间仅作预算参考,不代用户确定金额。 missing_fields不为空,就在创建之前一条一条问用户。没传daily_budget时,campaign.daily_budget保持空缺,别自己拍一个数字;用户给了答案再填回campaign。- 除补填的字段和用户批准的关键字改动外,把
campaign原样送去create_search_campaign预览。手里没有create_search_campaign这个工具、或can_write为 false 时,草稿就是终点:把方案交出去,让用户在 ADM 网页端自己建。草稿的投放范围仅限 Google 搜索,地区取自country_code(默认US),出价按传入的策略走(默认是尽可能提高转化次数)。用户确认之后,带着preview_id执行。新系列落地即暂停。 - 最后用
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. 轮换密钥
- 先到 API 密钥页面建一个新密钥。
- 把旧密钥替换掉:改
ADM_API_KEY,或者改 AI 工具 MCP 配置里那个密钥,之后重启 AI 工具。Claude Code 的请求头是添加服务器那一刻存下的,所以得先claude mcp remove adm,再按第 4 节重新添加。 - 凡是还在用旧密钥的电脑,第 2 步都要重做一遍。
- 盯一下旧密钥的「最近使用」时间,等到它不再变动,再把旧密钥撤销。
密钥要当密码对待:既不能提交进代码仓库,也不能写进项目文件。凡是粘进对话的密钥都会留在记录里,一旦这份记录可能外泄,就该轮换。判断有泄露风险时,立刻撤销。
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 会递上一段可直接复制的提示词。