io.github.davidmosiah/google-ads-mcp

Official

by davidmosiah · TypeScript

Unofficial Google Ads MCP for campaigns, keywords, budgets, and gated mutations.

Manage Google Ads campaigns, keywords, and budgets through an unofficial API integration.

Topics

ads-automationai-agentsgoogle-adslocal-firstmcpmcp-servermodel-context-protocoloauthppc

README.md10 KBView on GitHub

google-ads-mcp-unofficial

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.

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:

Prompts for: developer token, OAuth client id/secret, optional login_customer_id (MCC), redirect URI, privacy mode.
Writes ~/.google-ads-mcp/config.json with chmod 600.
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).
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:

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.
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=true, it gets:

code

Error: Write tools are disabled. To enable: re-run `google-ads-mcp-server setup --allow-mutations`
or set GOOGLE_ADS_ALLOW_MUTATIONS=true. 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:

code

[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=true`.
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

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.

Install

Configuration

Environment variables

GOOGLE_ADS_DEVELOPER_TOKENsecret

Google Ads API developer token from your Google Ads Manager account. Required.

GOOGLE_ADS_CLIENT_ID

Google OAuth2 client ID. Required.

GOOGLE_ADS_CLIENT_SECRETsecret

Google OAuth2 client secret. Prefer storing in ~/.google-ads-mcp/config.json via setup.

GOOGLE_ADS_LOGIN_CUSTOMER_ID

Manager (MCC) customer ID used as login-customer-id header, no dashes (e.g., 1234567890). Optional but required for multi-account access.

GOOGLE_ADS_REDIRECT_URI

OAuth redirect URI. Defaults to http://127.0.0.1:3000/callback.

GOOGLE_ADS_TOKEN_PATH

Optional local path for OAuth tokens. Defaults to ~/.google-ads-mcp/tokens.json (0600).

GOOGLE_ADS_PRIVACY_MODE

Optional payload mode: summary, structured, or raw. Defaults to structured. raw returns full Google Ads API payloads.

GOOGLE_ADS_ALLOW_MUTATIONS

Set to true to enable write tools (pause/resume keywords/campaigns, set bids, set budgets). Default false (read-only). Agents changing real ad spend is high-stakes; review every change.

GOOGLE_ADS_CACHE

Optional SQLite cache toggle. Set to true or sqlite to enable.

GOOGLE_ADS_CACHE_PATH

Optional local SQLite cache path. Defaults to ~/.google-ads-mcp/cache.sqlite.

GOOGLE_ADS_CACHE_TTL_SECONDS

Optional cache TTL in seconds. Defaults to 60. Set to 0 to keep entries indefinitely (entries are still overwritten on each hit).

GOOGLE_ADS_NO_RETRY

Set to true to disable the HTTP retry middleware. Default false.

claude_desktop_config.json

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "google-ads-mcp-unofficial@0.1.3"
      ],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "<YOUR_GOOGLE_ADS_DEVELOPER_TOKEN>",
        "GOOGLE_ADS_CLIENT_ID": "<YOUR_GOOGLE_ADS_CLIENT_ID>",
        "GOOGLE_ADS_CLIENT_SECRET": "<YOUR_GOOGLE_ADS_CLIENT_SECRET>",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "<YOUR_GOOGLE_ADS_LOGIN_CUSTOMER_ID>",
        "GOOGLE_ADS_REDIRECT_URI": "<YOUR_GOOGLE_ADS_REDIRECT_URI>",
        "GOOGLE_ADS_TOKEN_PATH": "<YOUR_GOOGLE_ADS_TOKEN_PATH>",
        "GOOGLE_ADS_PRIVACY_MODE": "<YOUR_GOOGLE_ADS_PRIVACY_MODE>",
        "GOOGLE_ADS_ALLOW_MUTATIONS": "<YOUR_GOOGLE_ADS_ALLOW_MUTATIONS>",
        "GOOGLE_ADS_CACHE": "<YOUR_GOOGLE_ADS_CACHE>",
        "GOOGLE_ADS_CACHE_PATH": "<YOUR_GOOGLE_ADS_CACHE_PATH>",
        "GOOGLE_ADS_CACHE_TTL_SECONDS": "<YOUR_GOOGLE_ADS_CACHE_TTL_SECONDS>",
        "GOOGLE_ADS_NO_RETRY": "<YOUR_GOOGLE_ADS_NO_RETRY>"
      }
    }
  }
}