# google-marketing-mcp

A read-only [MCP](https://modelcontextprotocol.io) 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](https://developers.google.com/google-ads/api/docs/get-started/dev-token))
- A **service account** with access to your Ads account, as base64-encoded JSON

## Setup

```bash
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

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

### Verify

```bash
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](LICENSE).