\n Google Ads MCP server — query campaigns, keywords, assets & more via natural language.\n \n Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client.\n
\n\n---\n\n## Quick Start\n\n### 1. Get Credentials\n\nYou need a [Google Ads API developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token) and OAuth client credentials.\n\n1. Download your OAuth client JSON from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)\n2. Set environment variables:\n\n```bash\nexport GOOGLE_ADS_DEVELOPER_TOKEN=your-token\nexport GOOGLE_ADS_CREDENTIALS_PATH=./credentials.json\n```\n\n3. Run the setup helper to authorize:\n\n```bash\nnpx mcp-gads setup\n```\n\nThis opens your browser, completes OAuth, and saves a refresh token.\n\n### 2. Add to Claude Code\n\n```bash\nclaude mcp add google-ads --scope user --transport stdio \\\n -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \\\n -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \\\n -- npx -y mcp-gads@latest\n```\n\nThat's it. Restart Claude Code and the tools are available. Every session runs the latest version automatically.\n\n> Also works with `bunx mcp-gads@latest` if you have [Bun](https://bun.sh/).\n> Requires Node 22+ when running via `npx`.\n\nIf your environment blocks npm registry access at runtime, install once and run the published binary name directly:\n\n```bash\nnpm i -g mcp-gads@latest\nclaude mcp add google-ads --scope user --transport stdio \\\n -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \\\n -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \\\n -- mcp-gads\n```\n\n\nAlternative: standalone binary\n\nDownload a pre-built binary from [Releases](https://github.com/pijusz/mcp-gads/releases):\n\n| Platform | File |\n|----------|------|\n| macOS (Apple Silicon) | `mcp-gads-darwin-arm64` |\n| macOS (Intel) | `mcp-gads-darwin-x64` |\n| Linux | `mcp-gads-linux-x64` |\n| Windows | `mcp-gads-windows-x64.exe` |\n\n**macOS / Linux:**\n\n```bash\ncurl -Lo mcp-gads https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-darwin-arm64\nchmod +x mcp-gads\nsudo mv mcp-gads /usr/local/bin/\nclaude mcp add google-ads --scope user --transport stdio \\\n -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \\\n -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \\\n -- /usr/local/bin/mcp-gads\n```\n\n**Windows (PowerShell):**\n\n```powershell\nInvoke-WebRequest -Uri \"https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-windows-x64.exe\" -OutFile \"$env:LOCALAPPDATA\\mcp-gads.exe\"\nclaude mcp add google-ads --scope user --transport stdio -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token -e GOOGLE_ADS_CREDENTIALS_PATH=C:\\path\\to\\credentials.json -- \"%LOCALAPPDATA%\\mcp-gads.exe\"\n```\n\n\n\n### ChatGPT Codex\n\nCodex uses TOML, not JSON. Install once, then add to `~/.codex/config.toml`:\n\n```bash\nnpm i -g mcp-gads\n```\n\n```toml\n[mcp_servers.gads]\ncommand = \"mcp-gads\"\n\n[mcp_servers.gads.env]\nGOOGLE_ADS_DEVELOPER_TOKEN = \"your-token\"\nGOOGLE_ADS_CREDENTIALS_PATH = \"/absolute/path/to/credentials.json\"\n```\n\nThree gotchas that cause silent failures on Codex:\n\n- **Don't use `npx -y` without raising the timeout.** Codex's default `startup_timeout_sec` is 10s, which is too short for npx's first-run download. A global install (above) or the [prebuilt binary](#quick-start) sidesteps this entirely. If you must use npx, add `startup_timeout_sec = 30`.\n- **Env vars must go under `[mcp_servers.gads.env]`.** Codex does not inherit the parent shell environment into stdio servers — exporting vars in your shell won't reach the server.\n- **Use absolute paths** for `GOOGLE_ADS_CREDENTIALS_PATH`. Codex spawns the server with its own cwd, so relative paths silently miss.\n\nOn Windows some Codex versions use `startup_timeout_ms = 20000` instead of `_sec`.\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n\nUsing npx (auto-updates)\n\n```json\n{\n \"mcpServers\": {\n \"google-ads\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-gads@latest\"],\n \"env\": {\n \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"your-token\",\n \"GOOGLE_ADS_CREDENTIALS_PATH\": \"/path/to/credentials.json\"\n }\n }\n }\n}\n```\n\n\n\n\nUsing binary (macOS / Linux)\n\n```json\n{\n \"mcpServers\": {\n \"google-ads\": {\n \"command\": \"/usr/local/bin/mcp-gads\",\n \"env\": {\n \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"your-token\",\n \"GOOGLE_ADS_CREDENTIALS_PATH\": \"/path/to/credentials.json\"\n }\n }\n }\n}\n```\n\n\n\n\nUsing binary (Windows)\n\n```json\n{\n \"mcpServers\": {\n \"google-ads\": {\n \"command\": \"C:\\\\Users\\\\YOU\\\\AppData\\\\Local\\\\mcp-gads.exe\",\n \"env\": {\n \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"your-token\",\n \"GOOGLE_ADS_CREDENTIALS_PATH\": \"C:\\\\path\\\\to\\\\credentials.json\"\n }\n }\n }\n}\n```\n\n\n\n## Tools (39)\n\n### Account Management\n| Tool | Description |\n|------|-------------|\n| `list_accounts` | List all accessible Google Ads accounts |\n| `get_account_currency` | Get the currency code for an account |\n| `get_account_hierarchy` | Get MCC account tree (manager -> client) |\n\n### Queries\n| Tool | Description |\n|------|-------------|\n| `execute_gaql_query` | Run any GAQL query (table output) |\n| `run_gaql` | Run GAQL with format options (table/json/csv) |\n| `get_gaql_help` | GAQL reference guide with syntax, resources, and examples |\n| `list_resources` | List valid GAQL FROM clause resources |\n\n### Campaigns\n| Tool | Description |\n|------|-------------|\n| `get_campaign_performance` | Campaign metrics (impressions, clicks, cost, conversions) |\n| `get_budget_utilization` | Budget amounts vs actual spend |\n\n### Ads\n| Tool | Description |\n|------|-------------|\n| `get_ad_performance` | Ad-level performance metrics |\n| `get_ad_creatives` | RSA headlines, descriptions, final URLs |\n\n### Assets\n| Tool | Description |\n|------|-------------|\n| `get_image_assets` | List image assets with URLs and dimensions |\n| `download_image_asset` | Download a specific image asset to disk |\n| `get_asset_usage` | Find where assets are used (campaigns, ad groups) |\n| `analyze_image_assets` | Image asset performance with metrics |\n\n### Keywords\n| Tool | Description |\n|------|-------------|\n| `generate_keyword_ideas` | Keyword Planner suggestions from seed keywords |\n| `get_keyword_volumes` | Historical search volume for specific keywords |\n| `get_quality_scores` | Quality scores with component breakdown |\n| `get_search_terms` | Actual search queries triggering your ads |\n| `get_paid_organic_search_terms` | Paid vs organic clicks per query (needs Search Console link) |\n| `get_search_term_insights` | Search demand categories — the only view into Performance Max & Demand Gen queries |\n\n### Geographic & Device\n| Tool | Description |\n|------|-------------|\n| `get_geographic_performance` | Performance by location |\n| `get_device_performance` | Performance by device type |\n\n### Insights\n| Tool | Description |\n|------|-------------|\n| `get_recommendations` | Google's AI optimization suggestions |\n| `get_change_history` | Recent account changes |\n\n### Extended Reporting\n\n| Tool | Description |\n|------|-------------|\n| `get_ad_group_performance` | Ad group metrics with optional campaign filter |\n| `get_conversion_actions` | Conversion actions with settings and performance |\n| `get_account_summary` | Quick dashboard: totals + top 5 campaigns |\n| `get_impression_share` | Competitive position: impression share and lost IS |\n| `get_ad_schedule_performance` | Performance by hour or day of week |\n| `get_audience_performance` | Demographics: age range and gender breakdowns |\n| `get_landing_page_performance` | Landing page URLs with metrics |\n| `get_placement_performance` | Display/PMax placement details |\n| `get_asset_group_performance` | PMax asset group metrics and ad strength |\n| `get_video_performance` | YouTube/video view rates and quartile completion |\n| `get_labels` | Labels and their campaign/ad group assignments |\n\n### Write Tools (disabled by default)\nEnable with `GOOGLE_ADS_ENABLE_MUTATIONS=true`:\n\n| Tool | Description |\n|------|-------------|\n| `update_campaign_status` | Pause/enable a campaign |\n| `update_ad_group_status` | Pause/enable an ad group |\n| `update_ad_status` | Pause/enable an ad |\n| `update_campaign_budget` | Change daily budget amount |\n| `add_negative_keywords` | Add negative keywords to a campaign |\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `GOOGLE_ADS_DEVELOPER_TOKEN` | Yes | — | API developer token |\n| `GOOGLE_ADS_CREDENTIALS_PATH` | Yes | — | Path to OAuth client JSON |\n| `GOOGLE_ADS_AUTH_TYPE` | No | `oauth` | `oauth` or `service_account` |\n| `GOOGLE_ADS_CUSTOMER_ID` | No | — | Default customer ID (skips passing it per tool) |\n| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | No | — | MCC manager account ID |\n| `GOOGLE_ADS_IMPERSONATION_EMAIL` | No | — | Service account impersonation email |\n| `GOOGLE_ADS_ENABLE_MUTATIONS` | No | `false` | Enable write tools |\n| `GOOGLE_ADS_ENV_FILE` | No | `.env` | Path to .env file (loaded if present, never overrides existing env) |\n| `GOOGLE_ADS_API_VERSION` | No | `v25` | Google Ads API version |\n\n## Updates\n\n**Using `npx @latest`** (recommended): You always get the latest version — no manual updates needed.\n\n**Using a binary**: The server checks for new releases on startup and logs to stderr if outdated:\n\n```\n[mcp-gads] v0.2.0 available (current: v0.1.0). Download: https://github.com/pijusz/mcp-gads/releases/latest\n```\n\nCheck your installed version:\n\n```bash\nmcp-gads --version\n```\n\nTo update, download the new binary and replace the old one.\n\n## Development\n\nRequires [Bun](https://bun.sh/).\n\n```bash\ngit clone https://github.com/pijusz/mcp-gads.git\ncd mcp-gads\nbun install\nbun test # tests\nbun run build # standalone binary\nbun run inspect # MCP Inspector\nbun run check # biome format + lint\n```\n\n## License\n\nMIT\n",
"bytes": 10052,
"sha": "1480fb4117e5f3f8b590fad31dd0115af23b867706e0ac3a5183d39a49a909ce",
"repo_slug": "pijusz/mcp-gads",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_pijusz_mcp_gads_08ec35b0/readme"
}
![\"mcp-gads\"](\"logo.svg\")
\n