# MCP Google Ads Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB.svg)](https://www.python.org)
[![MCP](https://img.shields.io/badge/MCP-2024--11--05-6366F1.svg)](https://modelcontextprotocol.io)

An MCP (Model Context Protocol) server that lets AI models query Google Ads data, manage keywords, adjust budgets, and audit accounts — directly from Claude, GPT, or any MCP-compatible client.

Ships with a **demo mode** that returns realistic mock data, so you can explore the full API without any Google Ads credentials.

## Architecture

```mermaid
graph LR
    A[AI Client<br>Claude / GPT] -->|MCP Protocol| B[MCP Server]
    B --> C{Mode?}
    C -->|Demo| D[Mock Data<br>Realistic fixtures]
    C -->|Live| E[Google Ads API<br>GAQL queries]
    B --> F[Resources<br>accounts, doctrines, health]
    B --> G[Tools<br>8 operations]
```

## Tools

| Tool | Description |
|------|-------------|
| `get_campaign_metrics` | Campaign performance: impressions, clicks, cost, conversions, CPA, ROAS |
| `get_search_terms` | Search term report with wasted spend detection |
| `get_keyword_metrics` | Keyword-level data with quality scores and bid info |
| `get_geo_performance` | Geographic breakdown by city/region |
| `add_negative_keyword` | Add negatives to campaigns or shared lists |
| `set_campaign_budget` | Adjust daily budgets |
| `adjust_keyword_bid` | Change CPC bids on individual keywords |
| `run_account_audit` | Comprehensive audit: wasted spend, low QS, high CPA, doctrine compliance |

## Resources

| URI | Description |
|-----|-------------|
| `ads://accounts` | List of managed accounts with IDs and labels |
| `ads://doctrines` | Operational rules engine (10 doctrines) |
| `ads://accounts/{id}/health` | Health score, alerts, and recommendations |
| `ads://status` | Server mode and connection info |

## Quick Start

### 1. Install

```bash
pip install -e .
```

### 2. Run in Demo Mode

```bash
mcp-google-ads
```

No configuration needed — demo mode is the default. The server returns realistic mock data modeled on home-service advertising (TV mounting, handyman services).

### 3. Connect to Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "mcp-google-ads"
    }
  }
}
```

### 4. Connect to Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "google-ads": {
      "type": "stdio",
      "command": "mcp-google-ads"
    }
  }
}
```

## Live Mode

To query real Google Ads data, set credentials in `.env`:

```bash
cp .env.example .env
# Fill in your Google Ads API credentials
```

Then start with demo mode disabled:

```bash
MCP_DEMO_MODE=0 mcp-google-ads
```

Required credentials:
- `GOOGLE_ADS_DEVELOPER_TOKEN` — from your Google Ads API Center
- `GOOGLE_ADS_CLIENT_ID` / `CLIENT_SECRET` — OAuth2 app credentials
- `GOOGLE_ADS_REFRESH_TOKEN` — generated via OAuth2 flow
- `GOOGLE_ADS_LOGIN_CUSTOMER_ID` — your MCC account ID
- `GOOGLE_ADS_CUSTOMER_IDS` — comma-separated managed account IDs

## Example Session

```
You: What are my top campaigns by ROAS?

Claude: I'll check your campaign metrics.

> get_campaign_metrics(date_range="LAST_30_DAYS")

Here are your campaigns ranked by ROAS:

1. Brand - Exact Match — 11.5x ROAS, $1,247 spend, 48 conversions
2. Emergency - Phrase Match — 5.4x ROAS, $892 spend, 12 conversions
3. Local - City Targeting — 3.1x ROAS, $2,100 spend, 22 conversions
4. Services - Broad Modified — 2.7x ROAS, $3,456 spend, 31 conversions
5. Competitor Conquest — 0.3x ROAS, $1,890 spend, 2 conversions ⚠️

The Competitor Conquest campaign is bleeding money at $945/conversion.
I'd recommend pausing it or adding tighter negative keywords.
```

## Project Structure

```
src/mcp_google_ads/
├── __init__.py         # Package metadata
├── server.py           # MCP server — tools, resources, entry point
└── demo_data.py        # Realistic mock data fixtures
```

## Author

**Ruslan Danelian** — [premium.ruslandanelian.com](https://premium.ruslandanelian.com)

I build MCP servers, Google Ads API automation, and AI agent systems for production use. This project is a sanitized example of the tooling I operate daily across 8 live ad accounts.

## License

MIT — see [LICENSE](LICENSE).