中文

Google Ads Skill & MCP Server for Claude Code, Codex, Cursor, Windsurf

The ADM Google Ads skill gives an AI coding tool two abilities: reading the Google Ads accounts you own, and assembling Search campaigns out of a plan written into a file. Claude Code, Codex, Cursor and Windsurf all work with it. A single file, SKILL.md, carries the workflow description, while the calls themselves travel through the ADM MCP server — the piece linking the AI tool to the Google Ads accounts your ADM account has connected.

  • Read on every plan: any ADM plan, Free included, can pull assets, ads, keywords, search terms and reports, and can research keywords with Google Keyword Planner data.
  • Write on paid plans: anything that creates — campaigns, ad groups, ads, assets, keywords or negative keywords — needs a paid plan (Starter, Professional or Enterprise).
  • Hosted ADM today: what the hosted ADM server serves right now is the read tools plus AI drafts. Write tools are still missing there, so a campaign gets created in Google Ads through the campaign wizard in ADM.
  • Preview before every change: each change is validated by ADM, which hands back a preview. Google Ads receives nothing until you approve.
  • New campaigns are paused: a campaign starts out paused and only a separate message from you switches it on.

Addresses and versions:

  • Skill file: https://adm.cc/docs/google-ads-skill/SKILL.md (the folder is named adm-google-ads)
  • MCP server: https://app.adm.cc/mcp (Streamable HTTP); an ADM API key goes in the Authorization: Bearer adm_xxx header
  • Contract version: 2026-10-03
  • GitHub: ownway18/adm-google-ads-skill

1. Get started in three steps

Step 1. Create an API key. Log in to ADM, go to https://app.adm.cc/apikeys, then pick the access level:

  • Read only: configuration and reports only. Any plan works, Free included.
  • Read & write: the write tools on top of reports. An active paid plan is required for those tools.

You see the complete key a single time, so copy it before the dialog closes.

Step 2. Ask the AI tool to install ADM. Take the prompt below, swap adm_xxx for your key, and send it. From section 5 the tool learns how to connect the ADM MCP server, save the skill file and test the connection. Restart the AI tool if it says so once finished.

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

That key stays in the conversation history. Where others might read that history, rotate the key in ADM (section 10). Setting the server up manually is covered in section 4.

Step 3. Give instructions in plain language. For instance: "Which campaigns of mine spent the most over the past 30 days?" or "Build the campaigns listed in plan.md." Section 3 lists further examples.

2. Which ADM tools the skill calls

What you ask for ADM tools
Choose or switch the Google Ads account get_accounts
Reports and questions about performance 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
Keyword ideas and search volume get_keyword_ideas, get_keyword_metrics
See performance by device (mobile, computer, tablet) get_device_performance
Lower or exclude bids on mobile, computer or tablet set_device_bid_adjustments
See which locations spent and converted get_location_performance, set_location_bid_adjustments
Confirm a preview with only its id confirm_preview
Build campaigns from a plan create_search_campaign, add_ad_groups, add_keywords, add_ads
Negative keywords add_account_negative_keywords, create_shared_negative_list, attach_shared_negative_list
Sitelinks, callouts, structured snippets, prices, promotions and calls add_sitelinks, add_callouts, add_structured_snippets, add_prices, add_promotions, add_calls
Business name add_business_name
Image assets and business logos Upload endpoint POST https://app.adm.cc/mcp/uploads, then add_images or add_business_logo
Ad groups drafted by ADM AI draft_ad_groups, get_ad_group_draft
A new campaign drafted by ADM AI draft_campaign, get_campaign_draft, then create_search_campaign
Check a build and resume after an interruption get_campaign_setup, get_operation
Enable or pause a campaign set_campaign_status
Pause a campaign, or change its name, daily budget, bidding or languages update_campaign
Add or remove targeted or excluded locations update_campaign_locations
Create, attach or change a shared portfolio bidding strategy get_bidding_strategies, create_bidding_strategy, attach_bidding_strategy, update_bidding_strategy
Pause or unlink an asset set_asset_link_status
Rename, pause, enable or rebid an ad group update_ad_group, set_ad_group_status
Edit the text of an existing ad update_ads
Enable, pause or remove ads or keywords set_ad_status, set_keyword_status
Add or remove negative keywords add_campaign_negative_keywords, remove_negative_keywords, add_shared_negative_keywords, remove_shared_negative_keywords
Tag clicks with a custom parameter, tracking template or final URL suffix set_url_options

Every tool and its parameters are described in section 6.

3. What you can say after setup

  • "Over the last 30 days, which of my campaigns burned the most budget, and what did each one convert?"
  • "Show me search terms from the past 14 days that spent money but produced no conversion."
  • "Find keyword ideas for https://www.example.com/photo-enhancer in Germany, with monthly search volume."
  • "Build the campaigns listed in plan.md, previewing first and waiting for my approval."
  • "Draft ad groups covering the photo-enhancer part of plan.md."
  • "Start a Search campaign from https://www.example.com/photo-enhancer. Explore keywords for it, preview, then wait for my approval."
  • "Attach banner.jpg to the photo-enhancer@DE campaign as an image asset."
  • "Move to the MySecond ad account."
  • "Put custom parameter myname on every campaign, so I can see where each click originated."

Default account

Where more than one Google Ads account is connected, a single question settles which one to use, and the answer goes into .adm/account.json inside the project directory — the customer ID and the account name, nothing else, never the API key. Requests made later in the same project reuse that account, and every operation states which account it is running on. A lone connected account is used without asking. "Switch to the MySecond ad account" replaces the choice. If the stored account gets disconnected in ADM later, the skill halts before its next operation, says that the saved account is no longer connected, and asks you to choose, even when a single account remains.

Optimization ledger

After each change you approve, the skill writes a dated entry to .adm/optimization-log.<customer_id>.md in the project directory: what changed (names and ids, before and after), any rule you settled during the session (for example "keep the 10-year guarantee headline"), and the checks that come due later, each with a date and a way to judge it. Every account has its own file, so switching accounts never mixes their history.

When a later session starts, the skill reads the ledger first. Checks due today or earlier come up before anything else, with a suggestion to run them, and the rules you settled are respected without being asked again. Sessions that only read reports leave the ledger unchanged, and no ledger is created until the first approved change. The file holds no API key; edit or delete it whenever you like.

Example: build a campaign from a plan

PixelUp is a fictional brand, and the example builds one campaign from a plan entry named photo-enhancer@DE: an online photo enhancement tool, advertised in Germany and in German.

Here is that entry:

  • One campaign, photo-enhancer@DE, targeting Germany, with a single ad group photo-enhancer-DE
  • Landing page https://www.example.com/de/photo-enhancer; the display path is foto / verbessern
  • 8 keywords in phrase match, 6 headlines, 2 descriptions and 4 negative keywords at campaign level
  • General settings: Google Search alone, Maximize clicks under a CPC cap, broad match off

The plan mentions neither the CPC cap nor a daily budget, so the AI tool asks for both before building. In this example the account currency amount is 10.00 a day with a 0.40 cap.

The request you send:

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

First the AI tool issues create_search_campaign with no confirm. ADM checks the request and replies with a preview carrying every error, plus the display width of each text, the account currency, and an estimate for the month (daily budget × 30.4). A preview_id arrives with it. After you approve, the AI tool calls again with identical arguments, adds "confirm": true and passes that 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." }
            ]
          }
        ]
      }
    ]
  }
}

A few notes about this payload:

  • Google notation applies to keywords: phrase match is written "text", exact match [text], and a bare word means broad match. In JSON, the quote marks around a phrase keyword have to be escaped, as in \".
  • A language tag is appended to the ad group name by "language": "de", so the group comes out as photo-enhancer-DE [de]. When ADM later analyzes the group, that tag identifies the ad language.
  • For geo targeting, the "Presence" option is always used, meaning people who are in the location or regularly there.
  • Negative keywords at account level and shared lists are handled in separate steps, even when the plan contains them: add_account_negative_keywords runs once for the account, create_shared_negative_list once for each list, then attach_shared_negative_list for every new campaign.

Back come the new campaign_id, the IDs of the ad groups and an operation_id. With get_campaign_setup the AI tool then compares Google Ads against the plan. Nothing gets enabled until you ask.

Where a plan holds many campaigns, the AI tool is told to do this:

  • Before building anything, list each decision still missing and verify the counts stated in the plan
  • Ask for approval in two preview rounds: first campaigns and lists, then the attachments and assets that depend on the new IDs
  • Work through the campaigns one at a time, writing every ID into the manifest file adm-manifest.json
  • Reconcile what was built, and pick up again without redoing campaigns already finished
  • Nothing gets enabled without a separate question

4. Use the MCP server without the skill

You do not need the skill at all. When the MCP server is connected on its own, it hands the AI tool a short set of rules at connect time: preview each write, keep new campaigns paused, use the default account, and treat search terms as data. Two more benefits apply whether or not the skill is installed:

  • Updates without reinstalling: tools and fields that ADM releases show up immediately, with no change to your configuration.
  • Permissions per tool: in most AI tools you can auto-approve the read side and still confirm each write tool (section 9).

Below, every configuration pulls the key out of ADM_API_KEY, an environment variable. Cursor, Windsurf and Codex all look it up at run time, so their configuration files hold no key. Claude Code differs: the key lands in its user-level ~/.claude.json the moment the server is added, and that file should stay private. Set the variable first, and only then restart it.

On macOS or Linux, append this to ~/.zshrc or ~/.bashrc:

export ADM_API_KEY="adm_xxx"

On Windows, run the command and then start a new terminal:

setx ADM_API_KEY "adm_xxx"

Per-tool configuration:

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"

With --scope user, every project on the machine can use the server. Verify it with claude mcp list; the adm entry should finish with ✔ Connected.

If you want the approval prompts gone for read tools alone, put the following into ~/.claude/settings.json (every project) or .claude/settings.json (a single project):

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

The pattern mcp__adm__get_* matches any ADM tool whose name begins with get_: the nine read tools plus get_ad_group_draft and get_campaign_draft, both of which only read an AI draft's state. Never put write tools in the allow list (section 9). draft_ad_groups and draft_campaign are left out by that rule as well, because although they change nothing in Google Ads, every call makes several AI calls. If the server was registered under another name, substitute that name for adm.

Codex:

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

When Codex starts, it reads ADM_API_KEY.

Cursor (~/.cursor/mcp.json for every project, or .cursor/mcp.json for one project):

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

Windsurf (config file ~/.codeium/windsurf/mcp_config.json):

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

The formats above are the ones documented for MCP by Codex, Cursor and Windsurf respectively. After editing a configuration, restart that tool and have it list your Google Ads accounts as a check. If the Windsurf file is not where the path says, reach it through View raw config in the MCP settings. Environment variables of the AI tool's own process supply ${env:ADM_API_KEY}. VS Code underlies both Cursor and Windsurf, which means a build launched from the Dock or an application launcher also reads what ~/.zshrc or ~/.bashrc defines. Any time you set or change the variable, quit the tool completely and start it fresh: on macOS use Cmd+Q, since closing the window keeps the app alive. Otherwise the header carries no key and HTTP 401 comes back from the server.

Connection troubleshooting

Symptom Cause Fix
HTTP 401 The key is missing, mistyped, or has leading or trailing spaces Check ADM_API_KEY, restart the AI tool, or remove the server and add it again with the key pasted exactly as shown
HTTP 401 The key was revoked on the API keys page Create a new key and update the configuration (section 10)
HTTP 401 on Windows The header used a PowerShell variable inside single quotes, so the variable was not expanded Use double quotes, or paste the key directly into the command
HTTP 401 after setting the variable The AI tool was started before the variable was set Quit the AI tool completely and open it again (on macOS, press Cmd+Q); start a terminal-based tool from a new terminal. If the error persists, start the editor from a terminal where the variable is set, for example cursor .
HTTP 404 The URL is wrong The URL must be exactly https://app.adm.cc/mcp: https, the app. subdomain, and the /mcp path
Timeout or connection refused A corporate proxy or firewall blocks the request Set HTTPS_PROXY before starting the AI tool, or ask your network administrator to allow app.adm.cc

When a key that used to work starts returning 401, revocation is the usual cause. Every key's last use is shown on the API keys page.

5. Installation steps (for AI tools to read)

The audience for this section is the AI tool itself. All you have to do is finish step 2 of section 1; from there the tool works through the steps below alone.

An ADM API key (prefixed adm_) has been handed to you by the user. Carry out the installation below, then report back what you did.

  1. Add the MCP server at user level, so every project can reach it. Name it adm, point it at https://app.adm.cc/mcp (Streamable HTTP) and send the header Authorization: Bearer <key>. The key belongs in your user-level MCP configuration only — never in a project file, never in a git repository. Where a server called adm is already present, replace it.
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 any other servers in the file untouched. On Windows, ~ refers to the user profile folder.

  1. Save the skill. Fetch https://adm.cc/docs/google-ads-skill/SKILL.md and put it at adm-google-ads/SKILL.md under whichever skills directory you consult in every project. The folder has to be named adm-google-ads, and any missing directories need creating. If that directory is unknown to you, fall back to the one at project level:
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. Test the connection. Issue get_accounts against the adm server. Should the tool only appear after a restart, mention it.

  2. Report to the user: where the configuration and the skill file ended up, whether a restart is needed, and which accounts were found. After a restart, saying "List my Google Ads accounts" verifies the setup.

Update the skill

A version number sits in the metadata of the skill file. Once that version goes stale, get_accounts answers with skill_update_hint and the AI tool passes the hint on to you a single time. Updating means downloading https://adm.cc/docs/google-ads-skill/SKILL.md, dropping it over the local adm-google-ads/SKILL.md (the same location as step 2), and restarting the AI tool.

6. Tool reference

Any tool that acts on an account expects customer_id as returned by get_accounts (format 123-456-7890), while get_operation, get_ad_group_draft and get_campaign_draft want nothing but their own ID. Amounts are major units of the account currency, 5.00 for instance, never micros. A report window (days) covers 1 to 30 full days in the time zone of the account, never including today, with 7 as the default. List tools stop at limit rows (1 to 200, 50 unless set) and hand back a next_cursor for the following page.

Read tools

Tool What it returns Key parameters
get_accounts Connected accounts (customer_id, name, currency, time zone), your plan, the key scope, whether writes are allowed, campaign creations left this month and write calls left today. With skill_version, also says whether the skill file needs an update (skill_update_hint). Call it first. skill_version
get_campaigns Campaigns with settings and performance, sorted by cost. Removed campaigns are never returned. days, status (ENABLED or PAUSED), limit, cursor
get_campaign_setup The configuration of one campaign. include is any of ad_groups, keywords, ads, assets (default ad_groups,keywords,ads, no assets). With ad_groups, campaign assets stay on the campaign and ad group assets stay on each ad group. assets alone returns both, and ad group rows keep level and ad_group_id. Ads include ad_strength, approval_status, review_status and policy_topics. Keyword id is the criterion id for set_keyword_status. device_bid_adjustments (only non-zero; -100 excludes that device) are on the campaign and each ad group. campaign_id, include
get_ads Responsive search ads with headlines, descriptions, pins, per-asset performance_label, ad strength and performance. text_contains matches headlines and descriptions. compact returns only ids and text. Each ad carries approval_status, review_status and, when Google flagged it, policy_topics (topic, type, and the flagged text or destination). approval_status as a filter returns ads with that review outcome, e.g. DISAPPROVED. id is the ad id for update_ads and set_ad_status. campaign_id, ad_group_id, approval_status, days, text_contains, compact, limit, cursor
get_keywords Keywords in Google notation with status, Quality Score, max CPC and performance. Filter with status, match_type and text_contains (quotes and brackets in the text are ignored). compact returns only id, text, status, campaign and ad group. id is the criterion id for set_keyword_status. campaign_id, ad_group_id, days, status, match_type, text_contains, compact, limit, cursor
get_search_terms Search queries that triggered your ads, with the matched keyword and performance. At most the top 10,000 rows by cost (truncated is true when capped). text_contains keeps the search terms that contain that text. group_by: "search_term" returns one row per search term with totals and ad_group_count. min_cost keeps rows at or above that cost in the account currency. campaign_id, ad_group_id, days, text_contains, group_by, min_cost, limit, cursor
get_negative_keywords Negative keywords by level: account, campaign, ad group and shared lists (with list IDs and attached campaigns). Each keyword id is the criterion id for remove_negative_keywords. campaign_id
get_assets Sitelink, callout, structured snippet, price, image, promotion, call, business name and business logo assets. level is customer, campaign or ad_group (omit it for all three). Also types, asset_ids, link_status, limit and cursor. asset_id is the id for set_asset_link_status. campaign_id, level, types, asset_ids, link_status, limit, cursor
get_bidding_strategies Portfolio (shared) bidding strategies: id, name, type, target CPA or ROAS, CPC ceiling, and the campaigns on each. none
get_device_performance Performance split by device (MOBILE, DESKTOP, TABLET), including conversion rate, cost per conversion and the current bid adjustment (0 = none, -100 = excluded). Search campaigns only. level is campaign (default) or ad_group. level, campaign_id, days, limit, cursor
get_location_performance Performance split by where the user was. granularity is country, region (default) or city. bid_adjustment_percent is set when that location is targeted and the bid is not 0. location_id can be passed to update_campaign_locations or set_location_bid_adjustments. granularity, campaign_id, days, limit, cursor
get_ad_groups Ad groups with status, campaign, max CPC, bidding, keyword count and ad count. Pass days to add performance per ad group, sorted by cost. campaign_id, status, days, limit, cursor
get_paused_summary How many campaigns, ad groups, keywords and ads are paused, with ids and names (200 per level). none
find_negative_conflicts Positive keywords blocked by a negative at account, shared list, campaign or ad group level. Optional hypothetical negatives and keywords (up to 50) are checked before you add them. campaign_id, negatives, keywords, limit, cursor
get_conversion_actions Conversion actions: name, status, type, category, primary (counts in the Conversions column), value settings, counting and attribution. include_metrics adds the last 30 complete days in the account time zone, and the response includes date_range. include_metrics
get_customizers Ad customizer attributes and their values at account, campaign and ad group level. Use {CUSTOMIZER.Name:default} in ad text; the length limit counts the default. none
get_keyword_ideas Keyword suggestions from Google Keyword Planner for seed keywords, a page URL, or both: avg_monthly_searches, competition (LOW, MEDIUM or HIGH), competition_index (0 to 100) and the low and high top-of-page bid. Sorted by searches, highest first; at most 500 ideas per call (truncated is true when Google has more). keywords (1 to 20 seeds), url, language (default en), country_codes (up to 10, default US), min_monthly_searches, include_monthly, limit, cursor
get_keyword_metrics The same metrics for keywords you already have. Match-type notation is accepted and ignored. Google merges close variants (for example car and cars) into one row and lists the others in close_variants, so fewer rows than requested_count can come back. keywords (1 to 200), language, country_codes, include_monthly, limit, cursor
get_operation The recorded result of a write call: pending, completed, partial, failed or unknown, and the resources that were created. operation_id

Keyword Planner figures cover the Google Search network only. Search volume is approximate, because Google rounds it into ranges. Bids are in the account currency, in major units. A field without data is omitted rather than set to zero, and a keyword missing from the result has no data, which does not mean zero searches. Results are cached for 24 hours per account and set of arguments.

Write tools

Previewing comes first for every write tool. Without confirm, the call validates the input and hands back a preview, changing nothing. That preview carries a preview_id. Once the user approves, either pass the preview_id to confirm_preview, or repeat the same tool call with identical arguments plus "confirm": true and the same preview_id. Omitting preview_id on a confirmed call yields invalid_argument. A preview_id that was never confirmed and is older than 30 minutes yields preview_required. Confirming a preview_id twice does not write twice: the second call returns the stored result, even past those 30 minutes. To repeat the same change, run the preview again and, after approval, confirm with the fresh preview_id.

Tool What it does Key parameters
create_search_campaign Creates a complete Search campaign in one call: budget, bidding, networks, locations, negative keywords, shared lists, ad groups, keywords and responsive search ads. Always created paused. campaign (see the example in section 3)
add_ad_groups Adds ad groups with keywords, negatives and ads to an existing Search campaign. Created paused unless status is ENABLED. campaign_id, ad_groups, status
add_keywords Adds keywords, paused keywords and ad group negative keywords to one ad group. Existing keywords are reported as exists. ad_group_id, keywords, paused_keywords, negative_keywords
add_ads Adds 1 to 3 responsive search ads to an existing ad group (same ad shape as add_ad_groups, including path1 and path2). A group holds at most 3, paused ads included. An ad with the same headlines and descriptions as an existing ad is reported as exists. New ads are enabled and serve after Google review when the group and campaign are enabled. ad_group_id, ads
update_ads Edits responsive search ads in place. The ad id stays. Up to 20 ads, all or none. headlines and descriptions replace the whole list. headline_replacements and description_replacements ({from, to}) change one asset by its exact text and keep its pin; empty to deletes it. Do not combine a replacement with the whole list on the same ad. The preview lists each ad before and after, plus a diff of added, removed, re-pinned and reordered text. ads: {ad_id, headlines?, headline_replacements?, descriptions?, description_replacements?, final_url?, path1?, path2?}
add_account_negative_keywords Adds negatives to the account-level list, which blocks them in every Search campaign, including running ones. keywords (up to 500)
create_shared_negative_list Creates a shared negative keyword list and optionally attaches it to campaigns in the same request. name, keywords (up to 1,000), campaign_ids
attach_shared_negative_list Attaches an existing shared list to campaigns. shared_list_id, campaign_ids
add_sitelinks Adds sitelinks: link text up to 25, two optional descriptions up to 35 each (both or neither), final URL. level, sitelinks, campaign_ids or ad_group_ids
add_callouts Adds callouts, up to 25 each. level, callouts, campaign_ids or ad_group_ids
add_structured_snippets Adds structured snippets. header must be an official header for language when you pass one (for example German Marken, Danish Typer). Without language, any official translation is accepted; an unknown language is warned and Google checks it on confirm. 3 to 10 values, up to 25 each. level, snippets (header, values, language), campaign_ids or ad_group_ids
add_prices Adds price assets with 3 to 8 offerings. language_code must be one of de, en, es, es-419, fr, it, ja, nl, pl, pt-BR, pt-PT, ru, sv. Currency must be one Google supports for price assets (USD, EUR, GBP and others; not DKK or NOK). level, prices, campaign_ids or ad_group_ids
add_promotions Adds promotion assets. promotion_target is at most 20 characters. Pass exactly one of percent_off (30 = 30% off) or money_amount_off with currency, in major units. language_code and final_url are required. Optional: occasion, discount_modifier UP_TO, one of promotion_code or orders_over_amount (also needs currency), and start_date / end_date (yyyy-MM-dd). level, promotions, campaign_ids or ad_group_ids
add_calls Adds call assets: country_code (2 letters) and phone_number. Optional call_conversion_reporting_state; with USE_RESOURCE_LEVEL_CALL_CONVERSION_ACTION, an optional call_conversion_action_id from get_conversion_actions (omitted = Google's default call conversion action). level, calls, campaign_ids or ad_group_ids
add_business_name Adds a business name asset, at most 25 characters. Serving depends on Google's eligibility checks; the preview lists them. level (customer or campaign), business_name, campaign_ids
add_business_logo Adds a business logo from an uploaded file (see Image uploads below): square 1:1, at least 128×128. Serving depends on Google's eligibility checks; the preview lists them. level (customer or campaign), logos (upload_id, optional name), campaign_ids
add_images Adds image assets to Search campaigns or ad groups from uploaded files (see Image uploads below). Results are per target. level (campaign or ad_group), images (upload_id, optional name), campaign_ids or ad_group_ids
set_campaign_status Pauses or enables up to 50 campaigns. Pass campaign_id and status, or campaigns. The preview lists each daily budget and the added daily and monthly estimate for campaigns that are not already enabled. Manual CPC campaigns whose ad groups are still at a placeholder max CPC (0.05 or less) are warned. campaign_id and status, or campaigns: {campaign_id, status}
confirm_preview Runs a preview the user approved. Pass only the preview_id. The stored arguments are replayed, so the hash and the idempotency ledger are the same as confirming the original tool. preview_id
set_location_bid_adjustments Sets a bid adjustment on a location the campaign already targets. -90 to 900, 0 clears it. Does not add or remove locations. Smart bidding ignores these adjustments. items: {campaign_id, location_id, adjustment_percent}
set_customizer_values Creates an ad customizer attribute if needed (TEXT, NUMBER, PRICE, PERCENT) and sets its value at account, campaign or ad group level. items: {name, type, value, level, campaign_id, ad_group_id}
update_campaign In one atomic change: renames a campaign, pauses it, and/or sets the daily budget, bidding or languages. status accepts only PAUSED. A shared budget is rejected. Passing bidding while the campaign uses a portfolio detaches it: the campaign bids on its own, and the preview names the portfolio it leaves. bidding.max_cpc is only the Maximize Clicks ceiling; MANUAL_CPC rejects it and ad group bids are set with update_ad_group. Search campaigns cannot set languages (Google removed that in September 2026); the preview says so and changes nothing else in that call. The budget preview shows the old and new daily amount and the monthly estimates. campaign_id, at least one of name, status (PAUSED), daily_budget, bidding, languages
update_campaign_locations Adds or removes targeted locations and excluded locations on one campaign, in one atomic change. Each location is {location_id} from get_campaign_setup or get_location_performance, or {country_code}. Removing an exclusion or adding a target widens delivery and can increase spend; the preview says so when the campaign is ENABLED. Removing the last targeted location makes the campaign target every location except remaining exclusions. Radius targets are not supported. campaign_id, at least one of add_targets, remove_targets, add_exclusions, remove_exclusions
set_device_bid_adjustments Sets device bid adjustments on Search campaigns and ad groups (up to 50), together or not at all. device is MOBILE, DESKTOP or TABLET. -100 excludes that device. -90 to 900 lowers or raises the bid. 0 clears it (an ad group then inherits the campaign). An ad group adjustment overrides the campaign. Maximize conversions, Target ROAS and Maximize conversion value ignore every value except -100. On Target CPA the adjustment changes that device's target CPA. Setting all three devices to -100 is rejected. items: {level, campaign_id, ad_group_id, device, adjustment_percent}
set_asset_link_status Pauses, enables or unlinks assets (up to 300). REMOVED unlinks and cannot be undone; the asset itself stays. An asset linked under more than one field type at that level is changed on every link. An account-level sitelink can still show on campaigns that already have sitelinks; the preview lists every campaign it can affect. Other asset types list campaigns that do not have their own asset of that type. Results are per link. items: {level, asset_id, campaign_id, ad_group_id, status}. level is customer, campaign or ad_group. status is ENABLED, PAUSED or REMOVED
create_bidding_strategy Creates a portfolio bidding strategy (TARGET_CPA, TARGET_ROAS, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE). MANUAL_CPC is rejected. max_cpc is an optional CPC ceiling. Optional campaign_ids (up to 50) attach in the same atomic change. ENABLED campaigns start a learning period. name, bidding, campaign_ids
attach_bidding_strategy Attaches campaigns to an existing portfolio (up to 50). Replaces each campaign's own bidding. A campaign on another portfolio leaves it. Results are per campaign. strategy_id, campaign_ids
update_bidding_strategy Renames a portfolio and/or changes its target CPA, target ROAS or CPC ceiling. The type cannot change. The new target applies to every campaign on the portfolio; the preview lists them. strategy_id, at least one of name, bidding
update_ad_group Renames an ad group, sets it to PAUSED or ENABLED, and/or sets max_cpc, in one atomic change. Does not remove the ad group. max_cpc is charged only when the campaign uses MANUAL_CPC; the preview says so otherwise. An enabled ad group spends as soon as its campaign is enabled. ad_group_id, at least one of name, status (ENABLED or PAUSED), max_cpc
set_ad_status Sets ads to ENABLED, PAUSED or REMOVED (up to 100). REMOVED cannot be undone. A paused ad still counts toward the 3 responsive search ads an ad group can hold. Does not change the campaign status. Results are per ad. ads: {ad_group_id, ad_id, status}
set_keyword_status Sets positive keywords to ENABLED, PAUSED or REMOVED (up to 300). Negative keywords are refused. REMOVED cannot be undone. Does not change the campaign status. Results are per keyword. keywords: {ad_group_id, criterion_id, status}
set_ad_group_status Sets ad groups to ENABLED, PAUSED or REMOVED (up to 50). REMOVED cannot be undone. Does not change the campaign status. An enabled ad group spends only when its campaign is already enabled. ad_groups: {ad_group_id, status}
add_campaign_negative_keywords Adds negative keywords on one campaign, in Google notation (up to 500). They apply to every ad group, including ad groups created later. Existing negatives are exists. campaign_id, keywords
remove_negative_keywords Removes negative keywords (up to 300). Only a negative keyword is removed. A location criterion is refused (update_campaign_locations); a language criterion is refused (update_campaign). REMOVED cannot be undone. items: {level, parent_id, criterion_id}. level is account, campaign, ad_group or shared_list. For account, parent_id may be omitted
add_shared_negative_keywords Appends negative keywords to an existing shared list (up to 500). Does not create a list. The account-level list is refused. The preview names campaigns the list is already attached to. shared_list_id, keywords
remove_shared_negative_keywords Removes keywords from an existing shared list by criterion id (up to 300). REMOVED cannot be undone. shared_list_id, criterion_ids
set_url_options Sets custom parameters, a tracking template and a final URL suffix on campaigns, ad groups or ads. Custom parameters merge by key (an empty value removes that key). A tracking template set here replaces the account-level template for that target. Does not change bids, budgets or status. level (campaign, ad_group or ad), targets (up to 20: id, custom_parameters, tracking_template, final_url_suffix)

Asset tools take level as customer (meaning all campaigns), campaign or ad_group; add_images narrows it to campaign and ad_group, while add_business_name and add_business_logo allow only customer and campaign. For set_url_options the choice is campaign, ad_group or ad. A single call to an asset tool may carry up to 20 items and 20 targets; an asset added to a running campaign starts serving once Google has reviewed it.

Tracking which campaign a click came from

Where an account-level tracking template exists, do not clone it across every campaign. Instead, give every campaign, ad group and ad its own custom parameter. Take a template like {lpurl}?utm_campaign={_myname}&utm_term={keyword}&utm_ag={_groupname}&utm_ad={_adname}: it pulls {_myname} from the campaign. Storage drops the underscore, so what you store is myname, and myname, _myname, {_myname} denote one and the same key. Ad group level holds _groupname, ad level holds _adname, set identically.

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

Custom parameters the campaign already has survive untouched. A key is removed with "value": "". Leaving out tracking_template and final_url_suffix keeps them; "" wipes one. A tracking template set at this level overrides whatever template the account defines for that target, and the preview tells you so. Preview, then confirm through the preview_id. Inspect url_options via get_campaign_setup; ads expose it through get_ads as well. All targets in a call change together, or none do. Review can be triggered again by changing an ad's URL options.

AI ad group drafts

draft_ad_groups works on an existing Search campaign and returns ad group drafts: ADM inspects the landing page, sorts the keywords into themes and composes responsive search ads per group. Google Ads stays untouched; a write-capable key on a paid plan is required. Drafting runs in the background, which is why a draft_id returns immediately.

Tool What it does Key parameters
draft_ad_groups Starts a draft and returns draft_id, status and poll_after_seconds. campaign_id, landing_page_url, keywords (1 to 200), language, paused_keywords, group_name_prefix (up to 100 characters), ads_per_group (1 to 3, default 1)
get_ad_group_draft The state of a draft: pending, running, done or failed. When done: ad_groups, primary_ad_group and warnings. When failed: error. draft_id

Using the draft:

  1. Invoke draft_ad_groups, then poll get_ad_group_draft at poll_after_seconds intervals until status reads done or failed. Most drafts complete in 1 to 3 minutes.
  2. Pass ad_groups to add_ad_groups exactly as drafted and preview it. Where add_ad_groups is unavailable or can_write is false, treat the draft as the deliverable: present it to the user. Each group name includes a prefix plus a language tag.
  3. primary_ad_group names the group carrying the most keywords. The paused keywords land there too, as does any keyword the draft left unassigned and, when a draft returns more than 20 groups, the keywords belonging to the surplus groups. Hand-written ads (add_ads) and negative keywords at ad group level (add_keywords) belong in this group only.

A draft survives 24 hours. Every draft fires several AI calls, so one ADM account may hold 60 drafts an hour, a budget draft_campaign shares. Do not resend identical input while a draft from it is still pending or running.

AI drafts of a new campaign

draft_campaign starts from a landing page and drafts an entire new Search campaign. ADM fetches that page, explores keywords or accepts the ones you supply, draws on Google Keyword Planner search volume where it is available, arranges them into themes and composes responsive search ads for every group. Nothing in Google Ads changes. When the draft finishes, hand campaign to create_search_campaign untouched (preview first). The requirements are a paid plan and a write-capable key, and the hourly draft cap is shared with draft_ad_groups. Creating the campaign still draws on the monthly quota, which create_search_campaign re-checks.

Tool What it does Key parameters
draft_campaign Starts a draft and returns draft_id, status, poll_after_seconds and explore_keywords. landing_page_url. Optional: keywords (0 to 200; omit to explore), explore_keywords (default false when keywords are set; ignored when they are omitted), language (default en), country_code (default US), daily_budget, bidding (default MAXIMIZE_CONVERSIONS), campaign_name, business_goal (SALES, LEADS or TRAFFIC, default SALES; it only guides the AI), ads_per_group (1 to 3, default 1)
get_campaign_draft The state of a draft: pending, running, done or failed. When done: campaign, missing_fields, warnings, strategy_notes, keyword_planner_used and, when Keyword Planner data was used, keyword_metrics (text, avg_monthly_searches, competition, optional close_variants per keyword). When failed: error. draft_id

Using a new-campaign draft:

  1. Invoke draft_campaign. Leaving keywords out lets ADM explore keywords on the landing page. Supplying keywords restricts the draft to those, unless explore_keywords is also set to true, which keeps them and allows ADM to add more. After that, poll get_campaign_draft at poll_after_seconds intervals until status reads done or failed. Most drafts complete in 1 to 3 minutes. For identical input, never start a second draft while one is pending or running.
  2. Where failed comes back, report error and start another draft only with the user's consent. Where done comes back, present the campaign name, the ad groups, and whatever warnings and strategy_notes came along.
  3. Show each keyword with its average monthly searches from keyword_metrics, naming the language and country of the draft. A keyword missing from keyword_metrics has no data, which does not mean zero searches. When keyword_planner_used is false, say that this draft has no search volume data; get_keyword_metrics can check the keywords afterwards. Keywords are removed or added only with the user's approval. A top-of-page bid range is a reference for the budget, not an amount chosen for the user.
  4. A non-empty missing_fields means asking the user for every entry before creation. When no daily_budget was passed, campaign.daily_budget stays empty; never make a budget up. Fill the value into campaign once the user replies.
  5. Hand campaign to create_search_campaign unmodified, apart from the filled-in fields and any keyword changes the user approved, and preview it. Should create_search_campaign be unavailable, or can_write false, the draft is the end of the line: show the plan to the user, who can finish the job in the ADM web app. Google Search is already the only network in the draft, the country comes from country_code (default US), and the bidding is the one you passed (Maximize conversions by default). Confirm with the preview_id once the user approves. The new campaign stays paused.
  6. Check the result with get_campaign_setup.

A draft survives 24 hours. A draft id from draft_ad_groups cannot be seen by get_campaign_draft, and vice versa.

Image uploads

Images have to reach ADM before add_images can link them. Send each file as multipart/form-data in the field file, using the same API key:

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

PowerShell users should call curl.exe with the same arguments.

Files in JPG or PNG format are accepted up to 5120 KB, and content — not the file name — determines the format. The add_images preview then verifies dimensions: a 1:1 square of at least 300×300 or a 1.91:1 landscape of at least 600×314, with 1% tolerance allowed on the ratio. Uploading demands a write-capable key on a paid plan, and it consumes one write call.

The response (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"
}

Each upload_id lives 24 hours (see expires_at) and belongs to the account that created it alone. Once it expires, add_images answers not_found; upload the file once more and preview again with the fresh upload_id.

An error comes back as {"error": {...}}, carrying code, message, field_path, fix and request_id:

HTTP status code Cause
400 invalid_argument The request is not multipart/form-data, the file field is missing, or the file is empty
401 unauthorized The API key is missing or invalid
403 permission_denied The key is read-only, or the plan does not include write access
404 none Wrong URL (the endpoint is POST https://app.adm.cc/mcp/uploads on the app. subdomain), or uploads are not yet available on hosted ADM
413 invalid_argument The file is larger than 5120 KB
415 invalid_argument The file is not a JPG or PNG image
429 quota_exceeded Daily safety limit reached (UTC)

Only accounts Google considers eligible display image assets: those open for 60 days or more, with recent Search spend, a clean policy record and no sensitive vertical, among other conditions. Elsewhere Google may refuse the link, or the images never serve at all. Duplicate detection works on content as well: an image identical to one the account already holds is reused, and linking one that already exists on the target reports exists.

Validation limits

Item Limit
Ad groups per call 20
Ads per ad group 3
Keywords 300 per ad group, 2,000 per call; each up to 80 characters and 10 words
Negative keywords 1,000 per list or campaign
Locations 50 per campaign; each is either country_code (ISO 3166-1 alpha-2) or location_id; at least one must be a positive target
Shared lists per create_search_campaign call 20
Headlines 3 to 15 per ad, display width up to 30
Descriptions 2 to 4 per ad, display width up to 90
Display path path1 and path2, display width up to 15 each
Names up to 255 characters
Images JPG or PNG up to 5120 KB; 1:1 at least 300×300 or 1.91:1 at least 600×314 (1% tolerance)
AI drafts 0 to 200 keywords per draft (a new-campaign draft may omit keywords), 1 to 3 ads per group

A CJK character takes 2 units of display width. Emoji are refused. For pins, pinned_field accepts HEADLINE_1 through HEADLINE_3, plus DESCRIPTION_1 and DESCRIPTION_2.

For bidding, type must be MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_CPA or TARGET_ROAS. Choose MANUAL_CPC and a max_cpc becomes mandatory, either on the campaign or per ad group; under MAXIMIZE_CLICKS the max_cpc field acts as the CPC cap. network_settings.google_search has to be true.

campaign.languages is accepted but never applied: Search campaigns get created without language targeting at campaign level. The ad language is recorded through the ad group language field instead.

7. Error codes

Every error shares one structure:

{
  "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": "..."
}
Code Meaning What to do
invalid_argument A field is missing, out of range or too long Correct every field listed in field_path and preview again
account_not_found The customer_id is not connected to your ADM account Use a customer_id from get_accounts, or connect the account in ADM
not_found The campaign, ad group, list or operation does not exist Look up the ID again with a read tool
permission_denied The key is read-only, or the plan does not include write access Create a read and write key, or upgrade the plan (action_url)
quota_exceeded No campaign creations left this month on your plan, or a daily safety limit was reached Upgrade the plan (monthly creations) or wait for the reset in the error
preview_required confirm: true or confirm_preview used a preview_id that was never confirmed and has no stored preview from the last 30 minutes Preview again, get approval, then confirm with the new preview_id. If this preview_id was already confirmed, call confirm_preview again; that returns the stored result
conflict A resource with the same name but different content already exists Check the existing resource; do not rename and recreate
busy Another write to this Google Ads account is running Wait retry_after_seconds, then retry
reauth_required Google authorization for ADM has expired Reconnect Google Ads in ADM (action_url)
google_ads_error Google Ads rejected the change (policy or validation) Read the Google reason in message and adjust
result_unknown The call timed out or was interrupted and the outcome is not known Call get_operation or get_campaign_setup first; if the change is missing, preview again and confirm with the new preview_id after approval
internal Server error Retry once; contact support with request_id if it repeats

A missing or invalid key produces HTTP 401 (unauthorized) before any tool executes. The table in section 4 covers troubleshooting.

No tool call runs longer than 45 seconds. Narrowing a large read with campaign_id is possible.

8. Quotas

Quota Free Starter Professional Enterprise
Read tools Yes Yes Yes Yes
Write tools No Yes Yes Yes
Campaign creations per month 1 (web only) 10 30 100
Write calls per day (UTC) Not available 3,000 3,000 3,000
AI drafts per hour Not available 60 60 60
  • Campaigns you build in the ADM web wizard count against that same monthly figure, which resets on your billing date. get_accounts reports what is left and when the reset falls. Once nothing is left, the error states your plan, its monthly allowance and the allowance of the plan above; upgrading lifts the cap at once.
  • Anything sent with confirm: true is a write call, as is every image upload. Previews are free.
  • The daily caps — write items, preview items, write calls and Google Ads queries — exist to stop runaway automation. Normal use sits far below them, every paid plan carries the same values, and they reset at 00:00 UTC.
  • One hourly limit covers both AI drafts (draft_ad_groups and draft_campaign), and neither counts as a write call. A draft_campaign run consumes no monthly campaign creation on its own; create_search_campaign is what consumes it.
  • Write access demands two things: a key that is allowed to write, and a plan that is active and paid.

9. Why write tools should not be auto-approved

Several read tools hand you text that other people wrote. Anyone who sees your ads can type a search term; names, ad text and asset text may come from an agency or a colleague. That search term may contain wording which reads like a command addressed to the AI tool. ADM marks the content as data and instructs the AI tool to ignore commands embedded in it, but no model can be trusted to obey every single time.

The approval prompt on write tools is precisely where the pending change becomes visible. Leave it switched on:

  • Auto-approve read tools and nothing else. In Claude Code that means allowing mcp__adm__get_* only, never mcp__adm__* or a named write tool.
  • With the ADM server connected, never disable the approval prompts the AI tool shows.
  • Go through every preview before approving it, above all budgets, update_ads (an ad whose text changes goes back to review) and any call that sets a status to ENABLED (set_campaign_status, update_ad_group, set_ad_group_status, set_ad_status, set_keyword_status). A campaign cannot be switched on through update_campaign. REMOVED is final.

10. Key rotation

  1. On the API keys page, generate a fresh key.
  2. Swap the key in: change ADM_API_KEY, or the key held in the AI tool's MCP configuration, then restart. Claude Code freezes the header when the server is added, so run claude mcp remove adm and add it afresh (section 4).
  3. Carry out step 2 on every computer still using the old key.
  4. Keep an eye on the "Last used" time for the old key; once it stops moving, revoke that key.

A key deserves the same care as a password. Never commit one to a repository or put it in project files. Whatever you paste into a chat stays in the conversation history, so rotate the key if others might read that history. Suspect a leak and you should revoke the key at once.

11. Changes you make in Google Ads

Creation is not their only job. A campaign can also be paused, renamed, and given another daily budget or bidding; languages change too, except on Search. Locations can be added to it or removed from it. Device bid adjustments are set there, mobile exclusion included. Shared portfolio bidding strategies can be created, attached and retargeted. Ad groups can be renamed, paused, enabled, rebid or removed, while ads and positive keywords can be enabled, paused or removed. An existing responsive search ad can be edited: headlines, descriptions, paths and final URL. Negative keywords can be added or taken away, assets paused or unlinked. URL options with custom parameters, a tracking template or a final URL suffix can be set on a campaign, ad group or ad. Enabling a campaign is possible only through set_campaign_status. REMOVED is final. Some changes belong in Google Ads itself:

  • Delete an asset nothing uses from the asset library (set_asset_link_status only unlinks it)
  • Apply language targeting to a Search campaign (Google dropped that in September 2026, so the campaign covers all languages)
  • Disable auto-apply recommendations (under Recommendations, then Auto-apply)
  • Configure conversion tracking
  • Add assets for location, mobile app, business message and lead form
  • Configure the ad schedule and your audience segments
  • Create campaign types besides Search, Performance Max among them
  • Handle billing and finish advertiser verification

12. Changelog

2026-11-13

  • New read tools, nothing broken: get_keyword_ideas (keyword suggestions from seed keywords, a page URL or both) and get_keyword_metrics (search volume, competition and top-of-page bid range for keywords you already have), both backed by Google Keyword Planner and available on every plan, Free included.
  • draft_campaign now uses Google Keyword Planner data when it drafts, and drafts as before when that data is unavailable. get_campaign_draft adds keyword_planner_used and keyword_metrics; campaign itself is unchanged. The contract version remains 2026-10-03.
  • Skill version 2026-11-13: the skill shows search volume next to drafted keywords, with the language and country, and changes keywords only with your approval. To get it, see Update the skill.

2026-11-11

  • Skill version 2026-11-11: an optimization ledger per account, .adm/optimization-log.<customer_id>.md. After each approved change the skill records what changed, the rules you settled and the checks that come due; the next session reads it first and reports due checks. No MCP tool changed. To get it, see Update the skill.

2026-10-13

  • Per ad, get_ads now reports approval_status, review_status and policy_topics, and approval_status also works as a filter. The same three fields appear on the ads returned by get_campaign_setup.
  • ad_group_id is now accepted by get_ads, get_keywords and get_search_terms.
  • Passing days to get_ad_groups adds per-ad-group performance.
  • get_search_terms takes group_by: "search_term" (totals, one row for each term) and min_cost.
  • get_keywords takes compact, and any quotes or brackets in the text_contains value are ignored.
  • Each ad in the update_ads preview now carries a diff.
  • Every addition is optional, so nothing breaks and the contract version remains 2026-10-03. The skill file moved to version 2026-10-13: see Update the skill.

2026-10-12

  • Any days value from 1 to 30 is now valid on the report tools (nothing breaks; the contract version remains 2026-10-03).
  • text_contains is available on get_search_terms; only search terms containing that text are kept.
  • The skill file gained a section called "Optimizing an account", which applies when the AI tool is asked to improve or optimize an account. The skill file is now at version 2026-10-12: see Update the skill.

2026-10-08

  • Hosted ADM now has the read tools and the AI drafts (draft_campaign, draft_ad_groups). Write tools are still absent there; where that is the case, a draft is handed over as a plan rather than created.
  • get_accounts takes skill_version and answers with skill_latest_version, skill_update_hint, upgrade_hint and upgrade_url (fields only, nothing breaks, contract version remains 2026-10-03). Skill file version 2026-10-08: see Update the skill.

2026-10-05

  • New tools, no breaking change: add_promotions, add_calls, add_business_name, add_business_logo. On get_assets, types now also takes promotion, call, business_name and business_logo, and set_asset_link_status can pause, enable or unlink those types.

2026-10-04

  • New: 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 now returns the portfolio strategy along with target CPA and target ROAS. On get_assets, filtering by level, types, asset_ids and link_status works alongside paging with limit / cursor. get_keywords filters by status, match_type and text_contains. get_ads gains text_contains, compact, and a performance_label per headline and per description. A targeted location now reports bid_adjustment_percent in get_location_performance.
  • Behavior change: assets come back from get_campaign_setup only when include lists assets; by default it covers ad_groups, keywords and ads. Ads carry ad_strength.
  • One set_campaign_status call holds up to 50 campaigns, and for those not yet enabled the preview sums their daily budgets. Enabling a manual CPC campaign produces a warning when an ad group still sits at a placeholder max CPC (0.05 or less). update_ads takes headline_replacements and description_replacements. add_prices rejects unsupported languages and currencies while previewing. add_structured_snippets verifies that the header matches the official translation in whichever language you supply. Keyword write previews now carry campaign_name and ad_group_name. After approval, confirm_preview needs nothing but its preview_id to replay a preview.
  • New tools, nothing broken: get_device_performance, set_device_bid_adjustments, get_location_performance. get_campaign_setup now reports device_bid_adjustments on the campaign and on each ad group. Excluding a location still goes through update_campaign_locations.
  • New tools, nothing broken: update_campaign_locations, set_asset_link_status, get_bidding_strategies, create_bidding_strategy, attach_bidding_strategy, update_bidding_strategy.
  • A portfolio strategy is no longer rejected by update_campaign. If you pass bidding, the campaign leaves its portfolio, and the preview names which one it left.

2026-10-03

  • Contract version 2026-10-03. This one breaks: update_campaign status now takes PAUSED alone. A campaign can be enabled only through set_campaign_status, and only after an explicit request. REMOVED is final.
  • New: 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. Batch results are reported per item, so a failure leaves the items that succeeded in place.
  • update_ads arrived as a new tool, nothing broken (the contract version remains 2026-10-03): a responsive search ad can be edited where it sits. Its id survives, and so does its performance history. Do not remove the ad and add a replacement.
  • update_campaign gained daily_budget (a shared budget refuses it), bidding (a portfolio strategy refuses it) and languages (an empty list means every language; Search campaigns get refused, and nothing else in that call changes). update_ad_group gained max_cpc. Keywords from get_campaign_setup now carry id, the criterion id.
  • New in contract version 2026-09-30, no breaking change: draft_campaign and get_campaign_draft. Starting from a landing page, ADM drafts an entire Search campaign, complete with grouping, keyword exploration and responsive search ads. Hand the finished campaign to create_search_campaign. The hourly draft cap is shared with draft_ad_groups.
  • New in contract version 2026-09-30, no breaking change: the write tools update_campaign and update_ad_group. One atomic change can rename an ad group or campaign and pause or enable it, for instance to record why it was paused. set_campaign_status behaves exactly as before.
  • New in contract version 2026-09-30, with no breaking change: the write tool set_url_options. A tracking template, a final URL suffix and custom parameters (merged by key) can be attached to a campaign, an ad group or an ad; an account-level tracking template then records which target produced the click. get_campaign_setup and get_ads return url_options whenever one of those three is set.

2026-09-30

  • The ADM MCP server shipped for the first time at contract version 2026-09-30.
  • Read tools, 9 in total: get_accounts, get_campaigns, get_campaign_setup, get_ads, get_keywords, get_search_terms, get_negative_keywords, get_assets, get_operation.
  • Write tools, 11 in total: 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.
  • The ADM skill adm-google-ads, which builds campaigns from a plan (section 3).
  • Also new inside that same contract version, with nothing broken: the write tools add_ads and add_images, the AI draft tools draft_ad_groups and get_ad_group_draft, the upload endpoint POST /mcp/uploads, and image assets inside get_assets and get_campaign_setup. AI drafts and image workflows are now part of the skill.
  • Documentation resides at /docs/google-ads-skill now. Reports and questions arrived in the skill, along with a default account saved per project and setup instructions for Codex, Cursor and Windsurf; the server instructions received the same default-account rule. The skill offers copyable prompts the first time a project is used.

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.