io.github.davidmosiah/google-ads-mcp
Unofficial Google Ads MCP for campaigns, keywords, budgets, and gated mutations.
Open source Open in the app JSON README (API)
About
Unofficial Google Ads MCP for campaigns, keywords, budgets, and gated mutations.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- davidmosiah
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Stars
- 4
- Last push
- 2026-09-07T12:19:04Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.davidmosiah/google-ads-mcp
README
# google-ads-mcp-unofficial
[](https://github.com/davidmosiah/google-ads-mcp-unofficial/actions)
[](https://www.npmjs.com/package/google-ads-mcp-unofficial)
[](https://www.npmjs.com/package/google-ads-mcp-unofficial)
[](LICENSE)
[](https://modelcontextprotocol.io)
> Unofficial Model Context Protocol server that lets AI agents read, analyze, and (gated) act on a Google Ads account — pause keywords, set bids, adjust budgets — without leaving your stack.
**Unofficial. Not affiliated with Google.** This is a local-first MCP server that speaks the Google Ads REST API directly. It does NOT include automated financial-account changes beyond what the Google Ads API allows. Always review proposed changes before enabling `GOOGLE_ADS_ALLOW_MUTATIONS`.
---
## HTTP (v2 stateless)
Default is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:
```bash
npx -y google-ads-mcp-unofficial --http
# GET http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp (sessionless)
```
Env: `GOOGLE_ADS_MCP_HOST`, `GOOGLE_ADS_MCP_PORT`, `GOOGLE_ADS_MCP_TRANSPORT=http`.
## Quick start (30 seconds)
```bash
npx -y google-ads-mcp-unofficial setup
```
The setup wizard collects your developer token + OAuth client, writes `~/.google-ads-mcp/config.json` (chmod 600), then walks you through the OAuth dance via a local callback at `http://127.0.0.1:3000/callback`.
Verify:
```bash
npx -y google-ads-mcp-unofficial doctor
```
Then add it to your agent (Claude Desktop, Cursor, Hermes, OpenClaw, Codex — see examples below).
---
## What it does
22 tools across 6 categories.
| Category | Count | Examples |
|---|---|---|
| **Meta / diagnostic** | 5 | `google_ads_connection_status`, `google_ads_capabilities`, `google_ads_agent_manifest`, `google_ads_data_inventory`, `google_ads_privacy_audit` |
| **Shared Delx profile** | 3 | `google_ads_profile_get`, `google_ads_profile_update`, `google_ads_onboarding` |
| **Auth** | 3 | `google_ads_get_auth_url`, `google_ads_exchange_code`, `google_ads_revoke_access` |
| **Reads** (always safe) | 8 | `google_ads_list_accounts`, `google_ads_list_campaigns`, `google_ads_get_campaign`, `google_ads_list_ad_groups`, `google_ads_list_keywords`, `google_ads_get_account_performance`, `google_ads_get_campaign_performance`, `google_ads_get_keyword_performance` |
| **Workflow** | 2 | `google_ads_daily_report`, `google_ads_find_waste` |
| **Mutations** (gated) | 6 | `google_ads_pause_keyword`, `google_ads_resume_keyword`, `google_ads_set_keyword_bid_micros`, `google_ads_set_campaign_budget_micros`, `google_ads_pause_campaign`, `google_ads_resume_campaign` |
Full tool reference: see `AGENTS.md`.
---
## Setup wizard
```bash
npx -y google-ads-mcp-unofficial setup [--allow-mutations] [--client hermes|claude|cursor|...]
```
What it does:
1. Prompts for: developer token, OAuth client id/secret, optional login_customer_id (MCC), redirect URI, privacy mode.
2. Writes `~/.google-ads-mcp/config.json` with `chmod 600`.
3. Writes an MCP client config (e.g. merges into `claude_desktop_config.json` on macOS; writes a Hermes block and skill file for `--client hermes`).
4. Runs the OAuth dance (unless `--no-auth`) by opening Google's consent screen and listening on `127.0.0.1:3000`.
> **Mutations are off by default.** `--allow-mutations` enables write tools. ASK THE USER before turning this on — it lets agents change campaigns, bids, budgets, and pause/resume keywords.
---
## Auth model
This MCP requires **two credentials**:
1. **Google Ads Developer Token** — from your MCC (Manager) account at https://ads.google.com/aw/apicenter. New tokens start in "Test account access" mode and need approval for production traffic.
2. **Google OAuth 2.0 Client** — a "Desktop" or "Web" client created in Google Cloud Console. The single OAuth scope used is `https://www.googleapis.com/auth/adwords`.
> ⚠️ **Refresh token gotcha:** Google only returns a `refresh_token` on first consent or after you revoke the prior grant at https://myaccount.google.com/permissions. Our `auth` flow uses `prompt=consent` to maximize the chance Google returns one — but if your code-exchange response is missing `refresh_token`, the tool will tell you to revoke and retry.
| Variable | Purpose | Stored where | Secret? |
|---|---|---|---|
| `GOOGLE_ADS_DEVELOPER_TOKEN` | Approved developer token | `~/.google-ads-mcp/config.json` or env | **yes** |
| `GOOGLE_ADS_CLIENT_ID` | OAuth client id | local or env | no |
| `GOOGLE_ADS_CLIENT_SECRET` | OAuth client secret | local or env | **yes** |
| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | MCC id (no dashes) | local or env | no |
| `GOOGLE_ADS_REDIRECT_URI` | OAuth callback | local or env (default `http://127.0.0.1:3000/callback`) | no |
| `GOOGLE_ADS_PRIVACY_MODE` | `summary` \| `structured` \| `raw` | local or env (default `structured`) | no |
| `GOOGLE_ADS_ALLOW_MUTATIONS` | Enable write tools | local or env (default `false`) | no |
| `GOOGLE_ADS_TOKEN_PATH` | Override token storage | local or env (default `~/.google-ads-mcp/tokens.json`) | no |
| `GOOGLE_ADS_CACHE` | Enable SQLite cache | local or env (default off) | no |
| `GOOGLE_ADS_CACHE_PATH` | Override cache path | local or env | no |
| `GOOGLE_ADS_NO_RETRY` | Disable retry middleware | env (default off) | no |
---
## Privacy modes
| Mode | What you get | Customer id |
|---|---|---|
| `summary` | id + name + status fields only | partial-redacted (`123-***-7890`) |
| `structured` (default) | flat normalized rows with metrics | partial-redacted |
| `raw` | full upstream Google Ads REST payload | **full** |
Pass `privacy_mode` per call to override the default per response.
**Redaction matrix:**
| Field | summary | structured | raw |
|---|---|---|---|
| developer_token | n/a | n/a | n/a (never returned) |
| access_token, refresh_token, client_secret | [REDACTED] in all errors | [REDACTED] | [REDACTED] |
| email addresses in error messages | [REDACTED] | [REDACTED] | [REDACTED] |
| customer_id | `123-***-7890` | `123-***-7890` | full |
| metrics (clicks, cost, etc.) | dropped | included | included |
---
## ⚠️ Mutation gating — read this
**Default: mutations are DISABLED.** Six tools are gated:
- `google_ads_pause_keyword` / `google_ads_resume_keyword`
- `google_ads_set_keyword_bid_micros`
- `google_ads_set_campaign_budget_micros`
- `google_ads_pause_campaign` / `google_ads_resume_campaign`
If an agent calls any of them without `GOOGLE_ADS_ALLOW_MUTATIONS` enabled, it gets:
```
Error: Write tools are disabled. To enable: re-run `google-ads-mcp-server setup --allow-mutations`
or enable GOOGLE_ADS_ALLOW_MUTATIONS. ASK THE USER BEFORE TURNING THIS ON — it lets agents
change campaigns, bids, budgets, and pause/resume keywords.
```
Even with the env enabled, **every mutation requires `explicit_user_intent: true`** in the per-call arguments. And every mutation is logged to stderr with the resource name:
```
[google-ads-mcp] MUTATION pause_keyword {"resource_name":"customers/1234567890/adGroupCriteria/999~111222333"}
```
Read `SECURITY.md` for the threat model.
---
## Agent client examples
### Claude Desktop
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"google-ads": {
"command": "npx",
"args": ["-y", "google-ads-mcp-unofficial"]
}
}
}
```
Then restart Claude Desktop.
### Cursor / Windsurf
`~/.cursor/mcp.json` (or your IDE equivalent):
```json
{
"mcpServers": {
"google-ads": {
"command": "npx",
"args": ["-y", "google-ads-mcp-unofficial@0.1.0"]
}
}
}
```
### Hermes
```yaml
# ~/.hermes/config.yaml
mcp_servers:
google-ads:
command: npx
args:
- -y
- google-ads-mcp-unofficial@0.1.0
timeout: 120
connect_timeout: 60
sampling:
enabled: false
```
Then `/reload-mcp` (do NOT restart the gateway for normal data access).
### OpenClaw
`~/.openclaw/mcp.servers.json`:
```json
{
"google-ads": {
"command": "npx",
"args": ["-y", "google-ads-mcp-unofficial@0.1.0"]
}
}
```
### Codex / TOML clients
See `examples/codex.toml` for the equivalent TOML block.
---
## Workflow examples
### 1. Daily performance pulse
```jsonc
// Agent asks: "How did my Google Ads do yesterday?"
{
"name": "google_ads_daily_report",
"arguments": {
"customer_id": "1234567890",
"cpc_alert_threshold": 0.15
}
}
```
Returns markdown with yesterday + 7d + 30d aggregates. If yesterday's CPC exceeds 0.15, the output gets an `ALERT` banner.
### 2. Identify waste (read-only)
```jsonc
{
"name": "google_ads_find_waste",
"arguments": {
"customer_id": "1234567890",
"date_range": "LAST_30_DAYS",
"min_clicks": 5,
"min_cost_micros": 200000,
"zero_conversions_only": true
}
}
```
Returns a ranked list of keywords matching "spent ≥ $0.20 with ≥5 clicks and 0 conversions" — but never pauses them.
### 3. Pause a single keyword (mutation, gated)
After the user confirms:
```jsonc
{
"name": "google_ads_pause_keyword",
"arguments": {
"customer_id": "1234567890",
"ad_group_id": "999",
"criterion_id": "111222333",
"explicit_user_intent": true
}
}
```
---
## Troubleshooting
| Symptom | Action |
|---|---|
| `Missing required Google Ads environment variables` | Run `setup` or set the env vars listed in the error. |
| `Google did not return a refresh_token` | Revoke at https://myaccount.google.com/permissions then re-run `auth`. |
| `PERMISSION_DENIED` on a read | Confirm `GOOGLE_ADS_LOGIN_CUSTOMER_ID` matches the MCC that owns the target customer (no dashes). |
| `Write tools are disabled` | Expected. Ask the user before enabling `GOOGLE_ADS_ALLOW_MUTATIONS`. |
| Hermes tools missing after config edit | `/reload-mcp` or `hermes mcp test google-ads`. Do NOT restart the gateway. |
| Token file insecure perms warning | `chmod 600 ~/.google-ads-mcp/tokens.json` |
---
## Support
- GitHub Issues: https://github.com/davidmosiah/google-ads-mcp-unofficial/issues
- Email: support@delx.ai
- X: [@delx369](https://x.com/delx369)
---
## Disclaimer
Unofficial integration. **Not affiliated with Google.** This MCP does not include automated financial-account changes beyond what the Google Ads REST API allows. Always review proposed changes before enabling `GOOGLE_ADS_ALLOW_MUTATIONS`. The author is not responsible for budget overruns, paused campaigns, or any other consequences of automated changes to your Google Ads account.
MIT-licensed.
## Skill or MCP
Same package, two doors. MCP registers tools on stdio/HTTP. The [skill](skill/SKILL.md) can drive the **same** tools through the CLI when the client has no MCP:
```bash
npx -y google-ads-mcp-unofficial call google_ads_connection_status --json '{}'
```
Copy `skill/SKILL.md` into your agent skills dir.