google-ads-mcp-unofficial

Unofficial Model Context Protocol server that lets AI agents read, analyze, and (gated) act on a Google Ads account — pause keywords, set bids, adjust budgets — without leaving your stack.

Unofficial. Not affiliated with Google. This is a local-first MCP server that speaks the Google Ads REST API directly. It does NOT include automated financial-account changes beyond what the Google Ads API allows. Always review proposed changes before enabling GOOGLE_ADS_ALLOW_MUTATIONS.

Quick start (30 seconds)

npx -y google-ads-mcp-unofficial setup

The setup wizard collects your developer token + OAuth client, writes ~/.google-ads-mcp/config.json (chmod 600), then walks you through the OAuth dance via a local callback at http://127.0.0.1:3000/callback.

Verify:

npx -y google-ads-mcp-unofficial doctor

Then add it to your agent (Claude Desktop, Cursor, Hermes, OpenClaw, Codex — see examples below).

What it does

22 tools across 6 categories.

| Category | Count | Examples | |---|---|---| | Meta / diagnostic | 5 | google_ads_connection_status, google_ads_capabilities, google_ads_agent_manifest, google_ads_data_inventory, google_ads_privacy_audit | | Shared Delx profile | 3 | google_ads_profile_get, google_ads_profile_update, google_ads_onboarding | | Auth | 3 | google_ads_get_auth_url, google_ads_exchange_code, google_ads_revoke_access | | Reads (always safe) | 8 | google_ads_list_accounts, google_ads_list_campaigns, google_ads_get_campaign, google_ads_list_ad_groups, google_ads_list_keywords, google_ads_get_account_performance, google_ads_get_campaign_performance, google_ads_get_keyword_performance | | Workflow | 2 | google_ads_daily_report, google_ads_find_waste | | Mutations (gated) | 6 | google_ads_pause_keyword, google_ads_resume_keyword, google_ads_set_keyword_bid_micros, google_ads_set_campaign_budget_micros, google_ads_pause_campaign, google_ads_resume_campaign |

Full tool reference: see AGENTS.md.

Setup wizard

npx -y google-ads-mcp-unofficial setup [--allow-mutations] [--client hermes|claude|cursor|...]

What it does:

1. Prompts for: developer token, OAuth client id/secret, optional login_customer_id (MCC), redirect URI, privacy mode.
2. Writes ~/.google-ads-mcp/config.json with chmod 600.
3. Writes an MCP client config (e.g. merges into claude_desktop_config.json on macOS; writes a Hermes block and skill file for --client hermes).
4. Runs the OAuth dance (unless --no-auth) by opening Google's consent screen and listening on 127.0.0.1:3000.

Mutations are off by default. --allow-mutations enables write tools. ASK THE USER before turning this on — it lets agents change campaigns, bids, budgets, and pause/resume keywords.

Auth model

This MCP requires two credentials:

1. Google Ads Developer Token — from your MCC (Manager) account at https://ads.google.com/aw/apicenter. New tokens start in "Test account access" mode and need approval for production traffic.
2. Google OAuth 2.0 Client — a "Desktop" or "Web" client created in Google Cloud Console. The single OAuth scope used is https://www.googleapis.com/auth/adwords.

⚠️ Refresh token gotcha: Google only returns a refresh_token on first consent or after you revoke the prior grant at https://myaccount.google.com/permissions. Our auth flow uses prompt=consent to maximize the chance Google returns one — but if your code-exchange response is missing refresh_token, the tool will tell you to revoke and retry.

| Variable | Purpose | Stored where | Secret? | |---|---|---|---| | GOOGLE_ADS_DEVELOPER_TOKEN | Approved developer token | ~/.google-ads-mcp/config.json or env | yes | | GOOGLE_ADS_CLIENT_ID | OAuth client id | local or env | no | | GOOGLE_ADS_CLIENT_SECRET | OAuth client secret | local or env | yes | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | MCC id (no dashes) | local or env | no | | GOOGLE_ADS_REDIRECT_URI | OAuth callback | local or env (default http://127.0.0.1:3000/callback) | no | | GOOGLE_ADS_PRIVACY_MODE | summary | structured | raw | local or env (default structured) | no | | GOOGLE_ADS_ALLOW_MUTATIONS | Enable write tools | local or env (default false) | no | | GOOGLE_ADS_TOKEN_PATH | Override token storage | local or env (default ~/.google-ads-mcp/tokens.json) | no | | GOOGLE_ADS_CACHE | Enable SQLite cache | local or env (default off) | no | | GOOGLE_ADS_CACHE_PATH | Override cache path | local or env | no | | GOOGLE_ADS_NO_RETRY | Disable retry middleware | env (default off) | no |

Privacy modes

| Mode | What you get | Customer id | |---|---|---| | summary | id + name + status fields only | partial-redacted (123-***-7890) | | structured (default) | flat normalized rows with metrics | partial-redacted | | raw | full upstream Google Ads REST payload | full |

Pass privacy_mode per call to override the default per response.

Redaction matrix:

| Field | summary | structured | raw | |---|---|---|---| | developer_token | n/a | n/a | n/a (never returned) | | access_token, refresh_token, client_secret | [REDACTED] in all errors | [REDACTED] | [REDACTED] | | email addresses in error messages | [REDACTED] | [REDACTED] | [REDACTED] | | customer_id | 123-***-7890 | 123-***-7890 | full | | metrics (clicks, cost, etc.) | dropped | included | included |

⚠️ Mutation gating — read this

Default: mutations are DISABLED. Six tools are gated:

• google_ads_pause_keyword / google_ads_resume_keyword
• google_ads_set_keyword_bid_micros
• google_ads_set_campaign_budget_micros
• google_ads_pause_campaign / google_ads_resume_campaign

If an agent calls any of them without GOOGLE_ADS_ALLOW_MUTATIONS=true, it gets:

Error: Write tools are disabled. To enable: re-run `google-ads-mcp-server setup --allow-mutations`
or set GOOGLE_ADS_ALLOW_MUTATIONS=true. ASK THE USER BEFORE TURNING THIS ON — it lets agents
change campaigns, bids, budgets, and pause/resume keywords.

Even with the env enabled, every mutation requires explicit_user_intent: true in the per-call arguments. And every mutation is logged to stderr with the resource name:

[google-ads-mcp] MUTATION pause_keyword {"resource_name":"customers/1234567890/adGroupCriteria/999~111222333"}

Read SECURITY.md for the threat model.

Agent client examples

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "google-ads-mcp-unofficial"]
    }
  }
}

Then restart Claude Desktop.

Cursor / Windsurf

~/.cursor/mcp.json (or your IDE equivalent):

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Hermes

# ~/.hermes/config.yaml
mcp_servers:
  google-ads:
    command: npx
    args:
      - -y
      - [email protected]
    timeout: 120
    connect_timeout: 60
    sampling:
      enabled: false

Then /reload-mcp (do NOT restart the gateway for normal data access).

OpenClaw

~/.openclaw/mcp.servers.json:

{
  "google-ads": {
    "command": "npx",
    "args": ["-y", "[email protected]"]
  }
}

Codex / TOML clients

See examples/codex.toml for the equivalent TOML block.

Workflow examples

1. Daily performance pulse

// Agent asks: "How did my Google Ads do yesterday?"
{
  "name": "google_ads_daily_report",
  "arguments": {
    "customer_id": "1234567890",
    "cpc_alert_threshold": 0.15
  }
}

Returns markdown with yesterday + 7d + 30d aggregates. If yesterday's CPC exceeds 0.15, the output gets an ALERT banner.

2. Identify waste (read-only)

{
  "name": "google_ads_find_waste",
  "arguments": {
    "customer_id": "1234567890",
    "date_range": "LAST_30_DAYS",
    "min_clicks": 5,
    "min_cost_micros": 200000,
    "zero_conversions_only": true
  }
}

Returns a ranked list of keywords matching "spent ≥ $0.20 with ≥5 clicks and 0 conversions" — but never pauses them.

3. Pause a single keyword (mutation, gated)

After the user confirms:

{
  "name": "google_ads_pause_keyword",
  "arguments": {
    "customer_id": "1234567890",
    "ad_group_id": "999",
    "criterion_id": "111222333",
    "explicit_user_intent": true
  }
}

Troubleshooting

| Symptom | Action | |---|---| | Missing required Google Ads environment variables | Run setup or set the env vars listed in the error. | | Google did not return a refresh_token | Revoke at https://myaccount.google.com/permissions then re-run auth. | | PERMISSION_DENIED on a read | Confirm GOOGLE_ADS_LOGIN_CUSTOMER_ID matches the MCC that owns the target customer (no dashes). | | Write tools are disabled | Expected. Ask the user before enabling GOOGLE_ADS_ALLOW_MUTATIONS=true. | | Hermes tools missing after config edit | /reload-mcp or hermes mcp test google-ads. Do NOT restart the gateway. | | Token file insecure perms warning | chmod 600 ~/.google-ads-mcp/tokens.json |

Support

• GitHub Issues: https://github.com/davidmosiah/google-ads-mcp-unofficial/issues
• Email: [email protected]
• X: @delx369

Disclaimer

Unofficial integration. Not affiliated with Google. This MCP does not include automated financial-account changes beyond what the Google Ads REST API allows. Always review proposed changes before enabling GOOGLE_ADS_ALLOW_MUTATIONS. The author is not responsible for budget overruns, paused campaigns, or any other consequences of automated changes to your Google Ads account.

MIT-licensed.