Google Ads
MCP server for Google Ads — 22 tools for spend diagnosis, impression share, and asset performance.
Open source Open in the app JSON README (API)
About
MCP server for Google Ads — 22 tools for spend diagnosis, impression share, and asset performance.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- zleventer
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 1
- Last push
- 2026-04-29T01:42:29Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:21
- Updated
- 2026-08-29 03:02:21
- Origin id
io.github.ZLeventer/google-ads-mcp
README
# google-ads-mcp
[](https://www.npmjs.com/package/@zleventer/google-ads-mcp)
[](https://www.npmjs.com/package/@zleventer/google-ads-mcp)
[](https://glama.ai/mcp/servers/ZLeventer/google-ads-mcp)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](LICENSE)
**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](https://developers.google.com/google-ads/api/docs/get-started/dev-token))
- 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`)
```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
```json
{
"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`)
```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
```bash
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
```bash
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