# Google Ads MCP Server

An MCP (Model Context Protocol) server for managing Google Ads campaigns through Claude Desktop, featuring a three-layer architecture for intelligent campaign management.

## Architecture

This MCP server uses a three-layer architecture:

### 1. Knowledge Layer (Resources)
Provides context and insights to Claude:
- **App Context**: Product information, value propositions, target audiences
- **User Archetypes**: Persona definitions, pain points, motivations
- **Keyword Research**: Keyword lists, search volumes, competition data

### 2. Action Layer (Tools)
Executes operations in Google Ads:
- **Campaigns**: List, create, update, pause campaigns
- **Ad Groups**: Manage ad groups within campaigns
- **Ads**: Create and manage responsive search ads
- **Keywords**: Add, update bids, pause keywords
- **Reports**: Generate performance reports

### 3. Memory Layer (Persistence)
Tracks history and learnings:
- **Change Log**: All modifications made to the account
- **Report History**: Past performance reports for comparison
- **Decisions**: Why certain choices were made
- **Learnings**: What worked, what didn't, insights gained

## Setup

### Prerequisites
- Python 3.10+
- Google Ads API credentials
- Claude Desktop

### Installation

1. Clone or download this repository

2. Create a virtual environment and install dependencies:
   ```bash
   # Using uv (recommended)
   uv venv
   uv sync

   # Or using pip
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e .
   ```

3. Configure your Google Ads credentials:
   ```bash
   cp .env.example .env
   # Edit .env with your credentials
   ```

### Google Ads API Credentials

You'll need the following credentials from the Google Ads API:

1. **Client ID & Secret**: Create OAuth 2.0 credentials in Google Cloud Console
2. **Developer Token**: Apply for one in your Google Ads account (Tools > API Center)
3. **Refresh Token**: Generate using the OAuth flow
4. **Customer ID**: Your Google Ads account ID (without dashes)

See the [Google Ads API documentation](https://developers.google.com/google-ads/api/docs/first-call/overview) for detailed setup instructions.

### Claude Desktop Configuration

Add this server to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/dev/mcps/google-ads",
        "run",
        "google-ads-mcp"
      ]
    }
  }
}
```

Or with environment variables in the config:

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["C:/dev/mcps/google-ads/src/server.py"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_developer_token",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_ADS_CUSTOMER_ID": "your_customer_id"
      }
    }
  }
}
```

## Knowledge Configuration

### Setting Up App Context

Copy and customize the example file:
```bash
cp data/knowledge/app_context.example.json data/knowledge/app_context.json
```

Edit `app_context.json` with your product/service information.

### Setting Up User Archetypes

Copy and customize the example file:
```bash
cp data/knowledge/archetypes.example.json data/knowledge/archetypes.json
```

Edit `archetypes.json` with your target audience personas.

## Available Tools

### Campaign Management
- `list_campaigns` - List all campaigns
- `get_campaign` - Get campaign details
- `create_campaign` - Create a new campaign
- `update_campaign` - Update campaign settings
- `set_campaign_status` - Pause/enable campaigns

### Ad Group Management
- `list_ad_groups` - List ad groups
- `create_ad_group` - Create an ad group
- `update_ad_group` - Update ad group settings

### Ad Management
- `list_ads` - List ads
- `create_responsive_search_ad` - Create an RSA
- `update_ad_status` - Change ad status

### Keyword Management
- `list_keywords` - List keywords
- `add_keywords` - Add new keywords
- `update_keyword_bid` - Adjust bids
- `pause_keyword` - Pause keywords

### Reporting
- `get_campaign_report` - Campaign performance
- `get_keyword_report` - Keyword performance
- `get_search_terms_report` - Search query data
- `get_performance_metrics` - Account summary

### Memory Tools
- `get_change_history` - View change log
- `save_report_snapshot` - Store reports
- `get_historical_reports` - Compare over time
- `log_decision` - Record decisions
- `get_decision_history` - View decisions
- `record_learning` - Store insights
- `get_insights` - Retrieve learnings

## Development

### Project Structure

```
google-ads/
├── src/
│   ├── server.py              # Main MCP server
│   ├── config.py              # Configuration
│   ├── google_ads_client.py   # API wrapper
│   ├── knowledge/             # Knowledge layer
│   ├── actions/               # Action layer (tools)
│   └── memory/                # Memory layer
├── data/
│   └── knowledge/             # Knowledge files
├── pyproject.toml
└── README.md
```

### Running Locally

```bash
# Run the server directly
python src/server.py

# Or using the entry point
google-ads-mcp
```

## License

MIT