google-ads-mcp

MCP server for Google Ads — diagnose spend efficiency, impression share, and asset performance from Claude.

22 tools across campaigns, keywords, RSAs, assets, audiences, geo/device splits, impression share, auction insights, and budget pacing — plus a raw GAQL escape hatch. Built for B2B paid search teams and agencies running real diagnosis, not just dashboard-style "list my campaigns" queries.

Why this exists

Most Google Ads MCP servers stop at "list campaigns + basic metrics." This one goes after the questions paid search teams actually ask: which RSA assets are labeled LOW so I can replace them, which keywords burn budget with zero conversions, who am I losing impression share to in auction insights, what's my mobile vs. desktop CPA gap, which campaigns are budget-limited right now. Those are the levers you pull to fix performance — and they're all first-class tools here.

Differentiated from the official googleads/google-ads-mcp: ships RSA asset performance labels, auction insights, impression share analysis, geo/device splits, audience targeting inspection, and budget pacing.

Example prompts

Once installed, ask Claude things like:

• "What's my impression share vs competitors this month? Who am I most often losing to?"
• "Show all RSA assets with LOW performance labels so I can replace them."
• "Which keywords are spending the most with zero conversions in the last 30 days?"
• "What's my mobile vs. desktop CPA difference across all campaigns?"
• "Are any campaigns budget-limited right now? Show Lost IS (Budget)."
• "List my remarketing audiences and tell me which ones are large enough to target in Search."

Demo

🎥 Walkthrough video coming soon — diagnosing wasted spend from Claude in under 60 seconds.

Features

| Category | Tools | |---|---| | Account | List accounts, account info | | Campaigns | List campaigns, campaign performance, ad group performance | | Keywords | Keyword performance, search terms report | | Conversions | Conversions by campaign, list conversion actions | | Ad Copy / RSAs | List RSAs with Ad Strength, RSA asset performance labels | | Assets / Extensions | List account assets, campaign assets | | Audiences | List user lists, campaign audience targeting | | Performance | Geo performance, device performance, impression share, auction insights | | Budget | List budgets, budget pacing | | Escape hatch | Raw GAQL query |

Prerequisites

• Node.js 20+
• A Google Ads Developer Token (apply here)
• OAuth 2.0 credentials (Client ID + Secret) from Google Cloud Console
• A refresh token with https://www.googleapis.com/auth/adwords scope

Environment variables

| Variable | Required | Description | |---|---|---| | GOOGLE_ADS_DEVELOPER_TOKEN | Yes | Your Google Ads developer token | | GOOGLE_ADS_CLIENT_ID | Yes | OAuth 2.0 client ID | | GOOGLE_ADS_CLIENT_SECRET | Yes | OAuth 2.0 client secret | | GOOGLE_ADS_REFRESH_TOKEN | Yes | OAuth 2.0 refresh token | | GOOGLE_ADS_CUSTOMER_ID | Yes* | Default customer ID (no dashes). Can be overridden per tool call. | | GOOGLE_ADS_LOGIN_CUSTOMER_ID | No | Manager account ID for MCC access |

Usage

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["/path/to/google-ads-mcp/dist/index.js"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Docker

docker build -t google-ads-mcp .
docker run --rm \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_TOKEN \
  -e GOOGLE_ADS_CLIENT_ID=YOUR_CLIENT_ID \
  -e GOOGLE_ADS_CLIENT_SECRET=YOUR_CLIENT_SECRET \
  -e GOOGLE_ADS_REFRESH_TOKEN=YOUR_REFRESH_TOKEN \
  -e GOOGLE_ADS_CUSTOMER_ID=1234567890 \
  google-ads-mcp

Tools reference

| Tool | Description | |---|---| | gads_run_gaql | Run any raw GAQL query — escape hatch for custom reports | | gads_list_accounts | List all accessible Google Ads accounts | | gads_account_info | Name, currency, timezone, manager flag, status | | gads_list_campaigns | Campaigns with status, channel type, bidding strategy | | gads_campaign_performance | Impressions, clicks, CTR, CPC, cost, conversions, CPA, ROAS | | gads_ad_group_performance | Ad group metrics with campaign context | | gads_keyword_performance | Keywords with match type, quality score, cost, conversions | | gads_search_terms_report | Actual user queries that triggered ads — find negatives and opportunities | | gads_conversions_by_campaign | Conversions × conversion action per campaign | | gads_list_conversion_actions | All conversion actions with category, type, counting method | | gads_list_rsas | RSAs with all headlines, descriptions, Ad Strength, approval status | | gads_rsa_asset_performance | Per-asset performance labels: BEST / GOOD / LOW / PENDING / LEARNING | | gads_list_assets | Account assets: sitelinks, callouts, structured snippets, images | | gads_campaign_assets | Assets linked to campaigns with field type | | gads_list_audiences | User lists (remarketing, customer match) with size and match rate | | gads_campaign_audience_targeting | Audiences on campaigns with bid modifiers and inclusion/exclusion | | gads_geo_performance | Performance by country, region, and city | | gads_device_performance | Cost, conversions, CPA split by MOBILE / DESKTOP / TABLET | | gads_impression_share | Search IS, Lost IS (Budget), Lost IS (Rank) per campaign | | gads_auction_insights | Impression share, overlap rate, outranking share vs competitors | | gads_list_budgets | All budgets: amount, delivery method, period, recommended budget | | gads_budget_pacing | Cost vs budget per campaign with utilization % |

Build from source

git clone https://github.com/ZLeventer/google-ads-mcp.git
cd google-ads-mcp
npm install
npm run build

License

MIT — Copyright (c) 2026 Zach Leventer