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

The ADM Google Ads skill lets an AI coding tool read your Google Ads accounts and build Search campaigns from a written plan. It works with Claude Code, Codex, Cursor and Windsurf. The skill is one file, SKILL.md, that describes the workflow; the work itself runs through the ADM MCP server, which connects the AI tool to the Google Ads accounts linked to your ADM account.

• Read on every plan: reports, search terms, keywords, ads and assets are available on every ADM plan, including Free.
• Write on paid plans: creating campaigns, ad groups, ads, keywords, negative keywords and assets requires a paid plan (Starter, Professional or Enterprise).
• Preview before every change: ADM validates each change and returns a preview. Nothing is written to Google Ads until you approve it.
• New campaigns are paused: every campaign is created paused and is enabled only when you ask for it in a separate message.

Addresses:

• Skill file: https://adm.cc/docs/google-ads-skill/SKILL.md (folder name adm-google-ads)
• MCP server: https://app.adm.cc/mcp (Streamable HTTP), authenticated with an ADM API key sent as Authorization: Bearer adm_xxx
• Contract version: 2026-09-30

1. Get started in three steps

Step 1. Create an API key. Sign in to ADM and open https://app.adm.cc/apikeys. Choose the access level:

• Read only: reports and configuration only. Works on every plan, including Free.
• Read & write: reports plus the write tools. Write tools require an active paid plan.

The full key is shown once. Copy it before closing the dialog.

Step 2. Ask the AI tool to install ADM. Copy the prompt below, replace adm_xxx with your key and send it to the AI tool. The AI tool follows the steps in section 5 to connect the ADM MCP server, save the skill file and test the connection. When it has finished, restart the AI tool if it asks you to.

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

The key remains in the conversation history. If that history may be seen by others, rotate the key in ADM (section 10). To configure the server by hand instead, see section 4.

Step 3. Give instructions in plain language. For example: "Which of my campaigns spent the most in the last 30 days?" or "Create the campaigns in plan.md." Section 3 has more examples.

2. Which ADM tools the skill calls

Section 6 describes every tool and its parameters.

3. What you can say after setup

• "Which of my campaigns spent the most in the last 30 days, and how many conversions did each get?"
• "List search terms from the last 14 days that cost money without a conversion."
• "Create the campaigns in plan.md. Preview first and wait for my approval."
• "Draft ad groups for the photo-enhancer section of plan.md."
• "Add banner.jpg as an image asset to the photo-enhancer@DE campaign."
• "Switch to the MySecond ad account."

Default account

When several Google Ads accounts are connected, the skill asks once which one to use and saves the choice in .adm/account.json in the project directory (customer ID and account name only, never the API key). Later requests in the same project use that account, and each operation names the account it runs on. When only one account is connected, the skill uses it without asking. To change the account, say "Switch to the MySecond ad account". If the saved account is later disconnected in ADM, the skill stops before the next operation, reports that the saved account is no longer connected, and asks which account to use, even when only one remains.

Example: build a campaign from a plan

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

The plan entry:

• Campaign photo-enhancer@DE, location Germany, one ad group photo-enhancer-DE
• Landing page https://www.example.com/de/photo-enhancer, display path foto / verbessern
• 8 phrase-match keywords, 6 headlines, 2 descriptions, 4 campaign negative keywords
• General settings: Google Search only, Maximize clicks with a CPC cap, no broad match

The plan does not state a daily budget or the CPC cap, so the AI tool asks for both before building anything. The example uses 10.00 per day and a 0.40 cap in the account currency.

What to ask:

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

The AI tool first calls create_search_campaign without confirm. ADM validates the request and returns a preview with every error, the display width of each text, the account currency and a monthly budget estimate (daily budget × 30.4). The preview includes a preview_id. After you approve, the AI tool sends the same arguments again with "confirm": true and 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." }
            ]
          }
        ]
      }
    ]
  }
}

Notes on this payload:

• Keywords use Google notation: "text" is phrase match, [text] is exact match, bare words are broad match. Inside JSON the quotes of a phrase keyword are escaped as \".
• "language": "de" appends a language tag to the ad group name, so the group is created as photo-enhancer-DE [de]. ADM uses this tag to identify the ad language when it analyzes the group later.
• Geo targeting always uses the "Presence" option (people in or regularly in the location).
• Account-level negative keywords and shared lists from the same plan are separate steps: add_account_negative_keywords once per account, create_shared_negative_list once per list, then attach_shared_negative_list for each new campaign.

The result contains the new campaign_id, the ad group IDs and an operation_id. The AI tool then calls get_campaign_setup to compare what exists in Google Ads with the plan. The campaign stays paused until you ask to enable it.

For a plan with many campaigns, the skill instructs the AI tool to:

• List every missing decision and check the counts in the plan before building
• Preview and ask for approval in two rounds: campaigns and lists first, then the list attachments and assets that need the new IDs
• Build campaign by campaign, recording each ID in the manifest file adm-manifest.json
• Reconcile the result, and resume without repeating finished campaigns
• Ask separately before enabling anything

4. Use the MCP server without the skill

The skill is optional. Connected on its own, the MCP server sends the AI tool a set of usage rules when it connects: preview before every write, new campaigns paused, the default account, and treating search terms as data. The MCP server has two further advantages, with or without the skill:

• Updates without reinstalling: new tools and fields become available as soon as ADM releases them; the configuration stays the same.
• Permissions per tool: most AI tools let you approve read tools automatically and keep a confirmation step for write tools (section 9).

The configurations below read the key from the ADM_API_KEY environment variable. Codex, Cursor and Windsurf read the variable at run time, and their configuration files do not contain the key. Claude Code writes the key into its user-level configuration file, ~/.claude.json, when the server is added; do not share that file. Set the variable first, then restart the AI tool.

macOS or Linux (add the line to ~/.zshrc or ~/.bashrc):

export ADM_API_KEY="adm_xxx"

Windows (then open a new terminal):

setx ADM_API_KEY "adm_xxx"

Configuration for each AI tool:

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 makes the server available in every project on this computer. Check the connection with claude mcp list: the adm line should end with ✔ Connected.

To stop the approval prompts for read tools only, add this to ~/.claude/settings.json (all projects) or .claude/settings.json (one project):

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

mcp__adm__get_* matches every ADM tool whose name starts with get_: the nine read tools and get_ad_group_draft, which only reads the state of an AI draft. Keep write tools out of the allow list (section 9). draft_ad_groups does not change Google Ads, but each call runs several AI calls, so the rule leaves it out as well. If you registered the server under another name, replace adm in the rule with that name.

Codex:

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

Codex reads ADM_API_KEY when it starts.

Cursor (~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a project):

{
  "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}" }
    }
  }
}

The Codex, Cursor and Windsurf entries follow each tool's documented MCP configuration format. Restart the AI tool after changing its configuration, then ask it to list your Google Ads accounts. In Windsurf, open the file from the MCP settings with View raw config if it is not at the path above. ${env:ADM_API_KEY} is read from the environment of the AI tool's own process. Cursor and Windsurf are based on VS Code and, when opened from the Dock or an application launcher, also load variables set in ~/.zshrc or ~/.bashrc. After setting or changing the variable, quit the AI tool completely and open it again (on macOS, press Cmd+Q; closing the window does not quit the app); otherwise the header is sent without the key and the server returns HTTP 401.

Connection troubleshooting

A key that worked before and now returns 401 has usually been revoked. The API keys page shows when each key was last used.

5. Installation steps (for AI tools to read)

This section is written for AI tools. You only need to complete step 2 of section 1; the AI tool then follows the steps below on its own.

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

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

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

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

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

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

6. Tool reference

Tools that act on an account take customer_id from get_accounts (format 123-456-7890); get_operation and get_ad_group_draft take only their own ID. Money is always in the account currency as major units, for example 5.00, never micros. Report windows (days) are 7, 14 or 30 complete days in the account time zone, excluding today (default 7). List tools return up to limit rows (1 to 200, default 50) and a next_cursor for the next page.

Read tools

Write tools

Every write tool previews first. Called without confirm, it validates and returns a preview without changing anything. Each preview returns a preview_id. Called again with identical arguments plus "confirm": true and that preview_id within 30 minutes of the preview, it performs the change. A confirmed call without preview_id returns invalid_argument; one whose preview_id is unknown, expired or was issued for different arguments returns preview_required. Retrying a confirm with the same preview_id returns the earlier result instead of writing twice. To make the same change again, preview again and confirm with the new preview_id after approval.

level is customer (all campaigns), campaign or ad_group; add_images accepts only campaign and ad_group. Asset tools accept up to 20 items and 20 targets per call; assets added to running campaigns start serving after Google reviews them.

AI ad group drafts

draft_ad_groups drafts ad groups for an existing Search campaign: ADM analyzes the landing page, groups the keywords by theme and generates responsive search ads for each group. It changes nothing in Google Ads and needs a read and write key and a paid plan. The draft runs in the background, so the call returns a draft_id at once.

How a draft is used:

1. Call draft_ad_groups, then call get_ad_group_draft every poll_after_seconds until status is done or failed. A draft usually finishes within 1 to 3 minutes.
2. Pass ad_groups verbatim to add_ad_groups and preview it. Group names carry the prefix and the language tag.
3. primary_ad_group names the group with the most keywords. It also receives the paused keywords, any keyword left unassigned by the draft, and the keywords of extra groups when the draft contains more than 20 groups. Add hand-written ads (add_ads) and ad group negative keywords (add_keywords) only to this group.

Drafts are kept for 24 hours. Each draft runs several AI calls; the limit is 60 drafts per hour per ADM account. Do not repeat a call for the same input while its draft is pending or running.

Image uploads

add_images links images that were uploaded to ADM first. Upload each file as multipart/form-data in the field file, with the same API key:

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

In PowerShell, use curl.exe with the same arguments.

The upload accepts JPG and PNG files up to 5120 KB; the format is detected from the file content, not the file name. The add_images preview then checks the dimensions: square 1:1 at least 300×300, or landscape 1.91:1 at least 600×314, with 1% tolerance on the aspect ratio. Uploads need a read and write key and a paid plan, and each upload counts as one write call.

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"
}

An upload_id is valid for 24 hours (expires_at) and only for the ADM account that uploaded it. After it expires, add_images returns not_found: upload the file again and preview again with the new upload_id.

Errors return {"error": {...}} with code, message, field_path, fix and request_id:

Google shows image assets only for eligible accounts, for example accounts that have been open for at least 60 days, have recent Search spend and a good policy history, and are not in a sensitive vertical. For other accounts Google may reject the link, or the images may not serve. Google also deduplicates images by content: an identical image already in the account is reused, and one already linked to the target is reported as exists.

Validation limits

Display width counts CJK characters as 2. Emoji are rejected. Pins use pinned_field values HEADLINE_1 to HEADLINE_3, DESCRIPTION_1 and DESCRIPTION_2.

Bidding type is one of MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_CPA and TARGET_ROAS. MANUAL_CPC requires max_cpc on the campaign or on each ad group; with MAXIMIZE_CLICKS, max_cpc is the CPC cap. network_settings.google_search must be true.

campaign.languages is accepted but not applied: Search campaigns are created without campaign-level language targeting. Use the ad group language field to record the ad language.

7. Error codes

Errors return 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": "..."
}

HTTP 401 (unauthorized) is returned before any tool runs when the key is missing or invalid. See the troubleshooting table in section 4.

Every tool call returns within 45 seconds. Large reads can be narrowed with campaign_id.

8. Quotas

• The monthly creation count is shared with campaigns created in the ADM web wizard and resets on your billing date. get_accounts shows the remaining count and the reset time.
• A write call is any call with confirm: true, plus each image upload. Previews do not count.
• AI drafts (draft_ad_groups) have their own hourly limit and do not count as write calls.
• Write access needs both a read and write key and an active paid plan.

9. Why write tools should not be auto-approved

Several read tools return text written by other people: search terms are typed by anyone who sees your ads, and ad text, asset text and names may come from colleagues or agencies. A search term can contain words that look like an instruction to the AI tool. ADM labels this content as data and asks the AI tool to ignore instructions inside it, but no AI model is guaranteed to follow that rule every time.

The approval prompt for write tools is the step where you see exactly what will change. Keep it in place:

• Approve only read tools automatically. In Claude Code, allow only mcp__adm__get_*; do not add mcp__adm__* or individual write tools to the allow list.
• Do not run the AI tool with approval prompts turned off while the ADM server is connected.
• Read each preview before approving, especially budgets and set_campaign_status calls.

10. Key rotation

1. Create a new key on the API keys page.
2. Replace the key: update ADM_API_KEY, or the key in the AI tool's MCP configuration, then restart the AI tool. Claude Code stores the header when the server is added, so run claude mcp remove adm and add the server again (section 4).
3. Repeat step 2 on each computer that uses the old key.
4. Watch the "Last used" time of the old key. When it no longer changes, revoke the old key.

Treat a key like a password. Do not commit it to a repository or write it into project files. A key pasted into a chat remains in the conversation history; rotate it if that history may be seen by others. If a key may have leaked, revoke it immediately.

11. Changes you make in Google Ads

The tools create and add; apart from pausing and enabling campaigns, they do not edit or remove existing items. Make these changes in Google Ads directly:

• Edit or remove existing ads, keywords, negative keywords or assets
• Change the budget or bidding of an existing campaign
• Turn off auto-apply recommendations (Recommendations, then Auto-apply)
• Set up conversion tracking
• Add logo, business name, call and lead form assets
• Set the ad schedule, device bid adjustments and audience segments
• Create campaign types other than Search, such as Performance Max
• Manage billing and complete advertiser verification

12. Changelog

2026-09-30

• First release of the ADM MCP server, contract version 2026-09-30.
• 9 read tools: get_accounts, get_campaigns, get_campaign_setup, get_ads, get_keywords, get_search_terms, get_negative_keywords, get_assets, get_operation.
• 11 write tools: 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 for building campaigns from a plan (section 3).
• Added in the same contract version (new tools and fields only, no breaking change): write tools add_ads and add_images, AI draft tools draft_ad_groups and get_ad_group_draft, the image upload endpoint POST /mcp/uploads, and image assets in get_assets and get_campaign_setup. The skill adds the AI draft and image workflows.
• Documentation moved to /docs/google-ads-skill. The skill adds reports and questions, a default account saved per project, and setup for Codex, Cursor and Windsurf; the server instructions add the same default account rule. On first use in a project, the skill suggests prompts the user can copy.