google-ads-write-mcp

MCP server that exposes write operations on Google Ads: campaigns, ad groups, keywords, RSA ads, sitelinks, images, Customer Match audiences and recommendations.

Complements the official google-ads MCP (read-only). Use the official one (or google-ads-kw-mcp) to read data, this one to write.

Tools (26)

Campaigns

Ad groups

Keywords

RSA ads

Sitelinks

Ad assets

Images

Audiences / Customer Match

Create full campaigns

Recommendations

Related MCP server: google-ads-mcp

Setup

Same credentials as google-ads-kw-mcp — you can point both at the same credentials.json.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

MCP client configuration

{
  "mcpServers": {
    "google-ads-write": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/google-ads-write-mcp/server.py"],
      "env": {
        "GOOGLE_ADS_CREDENTIALS_PATH": "~/.config/google-ads-mcp/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "<your developer token>",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "<your MCC customer id, no dashes>"
      }
    }
  }
}

Confirmation required for critical operations

These tools require confirmed=True. Called without it, they return a JSON with requires_confirmation: true that the calling agent MUST show to the user and wait for a response before repeating the call with confirmed=True.

# 1. First call — no confirmed
update_campaign_status(customer_id="1234567890", campaign_id="111222333", status="PAUSED")
# → returns requires_confirmation: true → show it to the user

# 2. Second call — after the user confirms
update_campaign_status(customer_id="1234567890", campaign_id="111222333", status="PAUSED", confirmed=True)

Gotchas found in production use

Auth

• Never use gcloud auth print-access-token — that token doesn't carry the adwords scope → 403. The only valid source is the refresh_token against oauth2.googleapis.com/token, which this server already does correctly.

Negatives vs. positives

• Adding a negative EXACT keyword to an ad group where the same keyword already exists as a positive EXACT match returns IMMUTABLE_FIELD. The fix is to pause the positive instead of adding the negative.

Resource names

• adGroupCriteria resource names always need a ~ between the ad group ID and the criterion ID: customers/{cid}/adGroupCriteria/{ag_id}~{crit_id}.

GAQL field limits

• ad_group_criterion doesn't accept metrics (clicks, cost, conversions) in the same query — query search_term_view separately for performance data.

• Filter ad_group_criterion by campaign with WHERE ad_group.campaign = 'customers/{cid}/campaigns/{campaign_id}', not campaign_id directly.

Budgets

• The budget is a separate entity (CampaignBudget). If a campaign shares a budget with others, changing it affects all of them.

contains_eu_political_advertising

• This is an enum (EuPoliticalAdvertisingStatus), not a bool. False serializes as UNSPECIFIED, which the API rejects as "not present". Use DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING explicitly.

PMax with Brand Guidelines

• If the account has Brand Guidelines enabled, PMax campaigns need a business_name and a logo (min. 128×128px, square) linked as CampaignAsset at creation time — not after.

RSA headline updates

• Use AdService.mutate_ads() with field mask "responsive_search_ad.headlines". Using AdGroupAdService with "ad.responsive_search_ad.headlines" gives IMMUTABLE_FIELD.

Removing a keyword

• Use the remove operation on AdGroupCriterionOperation. Trying an update with status = REMOVED gives INVALID_ENUM_VALUE.

REMOVED resources are immutable

• No write operation works on ad groups, keywords or ads whose parent campaign has status = REMOVED (OPERATION_NOT_PERMITTED_FOR_REMOVED_RESOURCE).

Customer Match allowlist

• upload_customer_match_emails fails with CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE unless your developer token has explicit Customer Match access. create_customer_match_list works without it — only the email upload needs the allowlist.

Notes

• Monetary amounts are passed in the account's currency units and converted to micros internally (1 unit = 1,000,000 micros).

• customer_id is always passed without dashes.

• update_rsa_headlines replaces ALL current headlines — pass the full desired list, not just the new ones.

• Customer Match lists can take up to 48h to process on Google's side.

License

MIT — see LICENSE.