google-marketing-mcp

A read-only MCP server that exposes the Google Ads API to LLM clients: campaigns, metrics, search terms, budgets, and change history.

Point Claude (or any MCP client) at your Ads account and ask questions like "which search terms spent over $50 with no conversions last month?" without handing it write access.

Read-only by construction

There is no write or mutation code path in this server. It isn't a permission flag that can be toggled or a prompt instruction that can be talked around: the mutate endpoints simply aren't implemented. Even if the underlying service account has write scope, a client connected here cannot change anything in your account.

Tools

Tool	What it does
list_accounts	Advertiser accounts under your manager (MCC) account. Start here to find customer ids.
get_campaigns	Campaigns: status, channel, bidding strategy, budget.
get_budgets	Campaign budgets (amount, status, delivery).
get_metrics	Cost, impressions, clicks, CTR, avg CPC, conversions by account / campaign / ad group / keyword / ad.
get_search_terms	Actual user queries with cost and conversions — negative-keyword candidates.
get_change_history	Native Ads change log (last 30 days).

Money fields are converted from micros to dollars, and nested rows are dot-flattened (campaign.name, metrics.cost), so results drop straight into a table without post-processing.

Requirements

• Node 20+
• A Google Ads developer token (apply here)
• A service account with access to your Ads account, as base64-encoded JSON

Setup

npm install && npm run build

Configuration

All configuration is via environment variables. Nothing is hardcoded — the server fails with a named error if a required variable is missing.

Variable	Required	Purpose
GOOGLE_ADS_DEVELOPER_TOKEN	yes	Google Ads API developer token
GOOGLE_SERVICE_ACCOUNT_KEY	yes	Service-account JSON, base64-encoded
GOOGLE_ADS_LOGIN_CUSTOMER_ID	yes	Your manager (MCC) account id
GOOGLE_ADS_CUSTOMER_ID	no	Default advertiser account; otherwise pass customer_id per call
GOOGLE_ADS_ENV_FILE	no	Path to a dotenv file to read the above from

Ids may be dashed or bare (123-456-7890 and 1234567890 are equivalent).

Resolution order is process environment first, then GOOGLE_ADS_ENV_FILE if set.

Add to Claude Code

claude mcp add google-marketing -- node /absolute/path/to/google-marketing-mcp/dist/index.js

Verify

npm test                    # unit tests, no network or credentials needed
npm run smoke               # end-to-end against the real API; needs credentials

License

MIT — see LICENSE.