# 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
