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