{
  "markdown": "# google-ads-mcp\n\n[![npm version](https://img.shields.io/npm/v/@zleventer/google-ads-mcp.svg)](https://www.npmjs.com/package/@zleventer/google-ads-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@zleventer/google-ads-mcp.svg)](https://www.npmjs.com/package/@zleventer/google-ads-mcp)\n[![glama score](https://glama.ai/mcp/servers/ZLeventer/google-ads-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ZLeventer/google-ads-mcp)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**MCP server for Google Ads — diagnose spend efficiency, impression share, and asset performance from Claude.**\n\n22 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.\n\n---\n\n## Why this exists\n\nMost 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.\n\nDifferentiated 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.\n\n---\n\n## Example prompts\n\nOnce installed, ask Claude things like:\n\n- *\"What's my impression share vs competitors this month? Who am I most often losing to?\"*\n- *\"Show all RSA assets with LOW performance labels so I can replace them.\"*\n- *\"Which keywords are spending the most with zero conversions in the last 30 days?\"*\n- *\"What's my mobile vs. desktop CPA difference across all campaigns?\"*\n- *\"Are any campaigns budget-limited right now? Show Lost IS (Budget).\"*\n- *\"List my remarketing audiences and tell me which ones are large enough to target in Search.\"*\n\n---\n\n## Demo\n\n> 🎥 *Walkthrough video coming soon — diagnosing wasted spend from Claude in under 60 seconds.*\n\n---\n\n## Features\n\n| Category | Tools |\n|---|---|\n| Account | List accounts, account info |\n| Campaigns | List campaigns, campaign performance, ad group performance |\n| Keywords | Keyword performance, search terms report |\n| Conversions | Conversions by campaign, list conversion actions |\n| Ad Copy / RSAs | List RSAs with Ad Strength, RSA asset performance labels |\n| Assets / Extensions | List account assets, campaign assets |\n| Audiences | List user lists, campaign audience targeting |\n| Performance | Geo performance, device performance, impression share, auction insights |\n| Budget | List budgets, budget pacing |\n| Escape hatch | Raw GAQL query |\n\n---\n\n## Prerequisites\n\n- Node.js 20+\n- A Google Ads Developer Token ([apply here](https://developers.google.com/google-ads/api/docs/get-started/dev-token))\n- OAuth 2.0 credentials (Client ID + Secret) from Google Cloud Console\n- A refresh token with `https://www.googleapis.com/auth/adwords` scope\n\n---\n\n## Environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `GOOGLE_ADS_DEVELOPER_TOKEN` | Yes | Your Google Ads developer token |\n| `GOOGLE_ADS_CLIENT_ID` | Yes | OAuth 2.0 client ID |\n| `GOOGLE_ADS_CLIENT_SECRET` | Yes | OAuth 2.0 client secret |\n| `GOOGLE_ADS_REFRESH_TOKEN` | Yes | OAuth 2.0 refresh token |\n| `GOOGLE_ADS_CUSTOMER_ID` | Yes* | Default customer ID (no dashes). Can be overridden per tool call. |\n| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | No | Manager account ID for MCC access |\n\n---\n\n## Usage\n\n### Claude Desktop (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"google-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"google-ads-mcp\"],\n      \"env\": {\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_TOKEN\",\n        \"GOOGLE_ADS_CLIENT_ID\": \"YOUR_CLIENT_ID\",\n        \"GOOGLE_ADS_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\",\n        \"GOOGLE_ADS_REFRESH_TOKEN\": \"YOUR_REFRESH_TOKEN\",\n        \"GOOGLE_ADS_CUSTOMER_ID\": \"1234567890\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```json\n{\n  \"mcpServers\": {\n    \"google-ads\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/google-ads-mcp/dist/index.js\"],\n      \"env\": {\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_TOKEN\",\n        \"GOOGLE_ADS_CLIENT_ID\": \"YOUR_CLIENT_ID\",\n        \"GOOGLE_ADS_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\",\n        \"GOOGLE_ADS_REFRESH_TOKEN\": \"YOUR_REFRESH_TOKEN\",\n        \"GOOGLE_ADS_CUSTOMER_ID\": \"1234567890\"\n      }\n    }\n  }\n}\n```\n\n### Cursor (`~/.cursor/mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"google-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"google-ads-mcp\"],\n      \"env\": {\n        \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_TOKEN\",\n        \"GOOGLE_ADS_CLIENT_ID\": \"YOUR_CLIENT_ID\",\n        \"GOOGLE_ADS_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\",\n        \"GOOGLE_ADS_REFRESH_TOKEN\": \"YOUR_REFRESH_TOKEN\",\n        \"GOOGLE_ADS_CUSTOMER_ID\": \"1234567890\"\n      }\n    }\n  }\n}\n```\n\n### Docker\n\n```bash\ndocker build -t google-ads-mcp .\ndocker run --rm \\\n  -e GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_TOKEN \\\n  -e GOOGLE_ADS_CLIENT_ID=YOUR_CLIENT_ID \\\n  -e GOOGLE_ADS_CLIENT_SECRET=YOUR_CLIENT_SECRET \\\n  -e GOOGLE_ADS_REFRESH_TOKEN=YOUR_REFRESH_TOKEN \\\n  -e GOOGLE_ADS_CUSTOMER_ID=1234567890 \\\n  google-ads-mcp\n```\n\n---\n\n## Tools reference\n\n| Tool | Description |\n|---|---|\n| `gads_run_gaql` | Run any raw GAQL query — escape hatch for custom reports |\n| `gads_list_accounts` | List all accessible Google Ads accounts |\n| `gads_account_info` | Name, currency, timezone, manager flag, status |\n| `gads_list_campaigns` | Campaigns with status, channel type, bidding strategy |\n| `gads_campaign_performance` | Impressions, clicks, CTR, CPC, cost, conversions, CPA, ROAS |\n| `gads_ad_group_performance` | Ad group metrics with campaign context |\n| `gads_keyword_performance` | Keywords with match type, quality score, cost, conversions |\n| `gads_search_terms_report` | Actual user queries that triggered ads — find negatives and opportunities |\n| `gads_conversions_by_campaign` | Conversions × conversion action per campaign |\n| `gads_list_conversion_actions` | All conversion actions with category, type, counting method |\n| `gads_list_rsas` | RSAs with all headlines, descriptions, Ad Strength, approval status |\n| `gads_rsa_asset_performance` | Per-asset performance labels: BEST / GOOD / LOW / PENDING / LEARNING |\n| `gads_list_assets` | Account assets: sitelinks, callouts, structured snippets, images |\n| `gads_campaign_assets` | Assets linked to campaigns with field type |\n| `gads_list_audiences` | User lists (remarketing, customer match) with size and match rate |\n| `gads_campaign_audience_targeting` | Audiences on campaigns with bid modifiers and inclusion/exclusion |\n| `gads_geo_performance` | Performance by country, region, and city |\n| `gads_device_performance` | Cost, conversions, CPA split by MOBILE / DESKTOP / TABLET |\n| `gads_impression_share` | Search IS, Lost IS (Budget), Lost IS (Rank) per campaign |\n| `gads_auction_insights` | Impression share, overlap rate, outranking share vs competitors |\n| `gads_list_budgets` | All budgets: amount, delivery method, period, recommended budget |\n| `gads_budget_pacing` | Cost vs budget per campaign with utilization % |\n\n---\n\n## Build from source\n\n```bash\ngit clone https://github.com/ZLeventer/google-ads-mcp.git\ncd google-ads-mcp\nnpm install\nnpm run build\n```\n\n---\n\n## License\n\nMIT — Copyright (c) 2026 Zach Leventer\n",
  "bytes": 7849,
  "sha": "541b22e74f1580903d1f7cdb71bd15ed3d419bd6200d1c0eddb41f5c00447163",
  "repo_slug": "zleventer/google-ads-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zleventer_google_ads_mcp_2806a31d/readme"
}