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.

HTTP (v2 stateless)

Default is stdio. Optional Streamable HTTP — no session id, JSON responses, loopback only:

npx -y google-ads-mcp-unofficial --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

Env: GOOGLE_ADS_MCP_HOST, GOOGLE_ADS_MCP_PORT, GOOGLE_ADS_MCP_TRANSPORT=http.

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.

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.

Privacy modes

Pass privacy_mode per call to override the default per response.

Redaction matrix:

⚠️ 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 enabled, it gets:

Error: Write tools are disabled. To enable: re-run `google-ads-mcp-server setup --allow-mutations`
or enable GOOGLE_ADS_ALLOW_MUTATIONS. 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", "google-ads-mcp-unofficial@0.1.0"]
    }
  }
}

Hermes

# ~/.hermes/config.yaml
mcp_servers:
  google-ads:
    command: npx
    args:
      - -y
      - google-ads-mcp-unofficial@0.1.0
    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", "google-ads-mcp-unofficial@0.1.0"]
  }
}

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