# Google Ads MCP Server

The definitive Google Ads MCP Server — 49 tools, 7 MCP Apps, tool annotations, lazy loading, safety guardrails.

## What Makes This Different

| Feature | Google Official | Others | **This** |
|---------|----------------|--------|----------|
| Tools | 2 | 8 | **49** |
| Tool Annotations | ❌ | ❌ | ✅ |
| Lazy Loading | ❌ | ❌ | ✅ |
| MCP Apps (Rich UI) | ❌ | ❌ | **7 apps** |
| Safety Guardrails | ❌ | ❌ | ✅ |
| Keyword Planner | ❌ | ❌ | ✅ |
| GAQL Query Builder | ❌ | ❌ | ✅ |
| Conversion Tracking | ❌ | ❌ | ✅ |
| Ad Management | ❌ | ❌ | ✅ |

## Quick Start

### 1. Install

```bash
npx @busybee/google-ads-mcp
```

### 2. Configure

Set credentials via environment variables:

```bash
# Option A: Inline JSON (simple)
export GOOGLE_ADS_CONFIG='{"client_id":"YOUR_ID","client_secret":"YOUR_SECRET","developer_token":"YOUR_TOKEN","refresh_token":"YOUR_REFRESH","login_customer_id":"YOUR_MANAGER_ID"}'
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

# Option B: Individual env vars
export GOOGLE_ADS_CLIENT_ID="YOUR_ID"
export GOOGLE_ADS_CLIENT_SECRET="YOUR_SECRET"
export GOOGLE_ADS_DEVELOPER_TOKEN="YOUR_TOKEN"
export GOOGLE_ADS_REFRESH_TOKEN="YOUR_REFRESH"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="YOUR_MANAGER_ID"  # optional
export GOOGLE_ADS_CUSTOMER_ID="1234567890"              # optional default
```

### 3. Add to MCP Client

**Claude Desktop / Cursor / Gemini CLI:**

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["@busybee/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_CONFIG": "{...}",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"
      }
    }
  }
}
```

## Tool Categories

### Always Loaded (24 core tools)
- **Account Management** (5) — list accounts, info, hierarchy, billing, budgets
- **Campaign Management** (8) — list, get, create, update, pause, enable, remove, budget
- **Reporting** (7) — performance summary, campaign/ad group/keyword/geo/device metrics, search terms
- **Advanced** (4) — raw GAQL queries, export CSV/JSON, change history, labels

### Lazy Loaded (25 tools, load on demand)
- **Ad Groups** (6) — list, get, create, update, pause, enable
- **Ads** (5) — list, get, create RSA, update, pause
- **Keywords** (6) — list, add, remove, keyword ideas, metrics, negatives
- **Bidding** (4) — strategies, bid recommendations, update bids, optimization recs
- **Conversions** (4) — list actions, conversion metrics, create actions, upload offline

Use `load_tools_category` to load additional categories on demand.

## MCP Apps (Rich UI)

7 interactive HTML dashboard components rendered via `structuredContent`:

1. **Campaign Dashboard** — Card grid with status pills, metrics, budget bars
2. **Performance Overview** — KPI cards, 7-day spend chart, top campaigns
3. **Campaign Detail** — Deep-dive with settings, budget, ad groups table
4. **Keyword Analyzer** — Quality score visualization, match type badges
5. **Search Terms Report** — Triggering terms with suggested actions
6. **Recommendations** — Google's optimization recs with impact scoring
7. **Budget Optimizer** — Allocation bars, over/underspend indicators

## Tool Annotations

Every tool is annotated with MCP hints:
- `readOnlyHint` — safe to call, no side effects
- `destructiveHint` — modifies account data
- `idempotentHint` — safe to retry
- `openWorldHint` — queries external data sources

## Safety Guardrails

- Campaigns created in **PAUSED** state by default
- Budget updates show **before → after** comparison
- Destructive operations clearly marked with ⚠️
- GAQL query runner blocks mutation keywords
- Remove operations warn about irreversibility

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── auth.ts               # OAuth2 token management
├── client.ts             # Google Ads API v21 REST client
├── types.ts              # Shared types + formatting
├── tools/
│   ├── index.ts          # Tool registry + lazy loading
│   ├── accounts.ts       # 5 account tools
│   ├── campaigns.ts      # 8 campaign tools
│   ├── ad-groups.ts      # 6 ad group tools
│   ├── ads.ts            # 5 ad tools
│   ├── keywords.ts       # 6 keyword tools
│   ├── reporting.ts      # 7 reporting tools
│   ├── bidding.ts        # 4 bidding tools
│   ├── conversions.ts    # 4 conversion tools
│   └── advanced.ts       # 4 utility tools
└── apps/
    ├── index.ts           # App registry
    ├── theme.ts           # Shared dark theme CSS
    ├── campaign-dashboard.ts
    ├── performance-overview.ts
    ├── campaign-detail.ts
    ├── keyword-analyzer.ts
    ├── search-terms.ts
    ├── recommendations.ts
    └── budget-optimizer.ts
```

## License

MIT
