# Google Ads MCP Server

MCP server that lets any LLM (Claude, Cursor, etc.) manage Google Ads campaigns from the terminal. Supports **read and write** operations.

## Quick Start

```bash
pip install google-ads-mcp
google-ads-mcp auth
```

The `auth` command walks you through getting credentials, opens your browser for Google sign-in, and saves everything to `~/.config/google-ads-mcp/credentials.json`.

Then add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "google-ads-mcp",
      "args": ["serve"]
    }
  }
}
```

No environment variables needed — the server auto-loads saved credentials.

### Alternative: uvx (no install)

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "uvx",
      "args": ["google-ads-mcp", "serve"]
    }
  }
}
```

Run `uvx google-ads-mcp auth` first to set up credentials.

### Alternative: environment variables

If you prefer env vars over saved credentials:

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "google-ads-mcp",
      "args": ["serve"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CLIENT_ID": "your-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

Env vars take priority over saved credentials when both are present.

## Tools (10)

### Read
- `list_accounts` — List accessible customer accounts
- `list_campaigns` — List campaigns with status & budget
- `get_campaign_performance` — Impressions, clicks, cost, conversions, CTR, CPC

### Write
- `create_campaign` — Create a search campaign (PAUSED by default)
- `update_campaign_budget` — Change daily budget
- `pause_campaign` / `enable_campaign` — Toggle campaign status
- `create_ad_group` — Create ad group in a campaign
- `add_keywords` — Add keywords to an ad group (EXACT, PHRASE, BROAD)
- `create_ad` — Create responsive search ad

## Development Setup

```bash
cd google_ads_mcp
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Tests

```bash
pytest tests/ -v
```

All tests use mocked Google Ads client — no credentials needed.

## Design decisions

- **Dollar amounts** in params (not micros) — LLMs think in dollars
- **Campaigns created PAUSED** by default — safety first
- **All tools return JSON** — structured output for LLMs
- **Errors return JSON too** (never raise) — actionable diagnostics
- **Lazy client init** — defers credential validation to first call
- **Credential priority**: env vars > saved file (`~/.config/google-ads-mcp/credentials.json`)