# Quick Start Guide - Google Ads MCP
## Installation
```bash
pip install mcp google-ads
```
## Configuration
1. Copy `.env.example` to `.env`
2. Add your Google Ads API credentials:
```
GOOGLE_ADS_DEVELOPER_TOKEN=your_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token
```
3. Add to Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"google-ads": {
"command": "python",
"args": ["/path/to/server.py"],
"env": {
"GOOGLE_ADS_DEVELOPER_TOKEN": "your_token",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your_customer_id",
"GOOGLE_ADS_CLIENT_ID": "your_client_id",
"GOOGLE_ADS_CLIENT_SECRET": "your_secret",
"GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token"
}
}
}
}
```
## Common Prompts
### "List my campaigns"
```python
campaigns = call_tool('list_campaigns', {'customer_id': 'YOUR_ID'})
```
### "What's my campaign performance last 30 days?"
```python
perf = call_tool('get_performance', {
'level': 'campaign',
'customer_id': 'YOUR_ID',
'date_range': 'LAST_30_DAYS',
'metrics': ['impressions', 'clicks', 'conversions', 'cost_micros']
})
```
### "Show keywords with quality score < 5"
```python
result = call_tool('execute_gaql', {
'query': 'SELECT ad_group_criterion.keyword.text, metrics.quality_score FROM ad_group_criterion WHERE metrics.quality_score < 5',
'customer_id': 'YOUR_ID'
})
```
### "Get my best performing ad groups"
```python
perf = call_tool('get_performance', {
'level': 'ad_group',
'customer_id': 'YOUR_ID',
'date_range': 'LAST_30_DAYS'
})
top = sorted(perf, key=lambda x: x.get('metrics', {}).get('conversions', 0), reverse=True)[:10]
```
### "Shopping campaign ROI analysis"
```python
result = call_tool('execute_gaql', {
'query': '''SELECT campaign.name, metrics.conversions, metrics.cost_micros
FROM campaign
WHERE campaign.advertising_channel_type = 'SHOPPING'
AND segments.date DURING LAST_30_DAYS''',
'customer_id': 'YOUR_ID'
})
```
## GAQL Cheat Sheet
### Date Filters
- `LAST_7_DAYS`, `LAST_30_DAYS`, `LAST_90_DAYS`
- `LAST_MONTH`, `LAST_QUARTER`, `LAST_YEAR`
- `THIS_MONTH`, `THIS_QUARTER`, `THIS_YEAR`
### Common Metrics
- `metrics.impressions` - Total impressions
- `metrics.clicks` - Total clicks
- `metrics.conversions` - Total conversions
- `metrics.cost_micros` - Cost (in millionths of currency)
- `metrics.ctr` - Click-through rate
- `metrics.conversion_rate` - Conversion rate
- `metrics.quality_score` - Quality score (1-10)
- `metrics.average_cpc` - Average cost per click
### Common Segments
- `segments.date` - By date
- `segments.device` - Mobile, Tablet, Desktop
- `segments.geo_target_country` - By country code
- `segments.day_of_week` - 1-7 (Monday-Sunday)
- `segments.hour_of_day` - 0-23
### Campaign Types
- `SEARCH` - Search Network
- `DISPLAY` - Display Network
- `SHOPPING` - Shopping campaigns
- `VIDEO` - YouTube/video campaigns
- `APP` - App campaigns
- `PERFORMANCE_MAX` - Performance Max
## Output Formats
All queries support three formats:
```python
# JSON (default)
call_tool('execute_gaql', {..., 'output_format': 'json'})
# CSV - great for importing to sheets
call_tool('execute_gaql', {..., 'output_format': 'csv'})
# Table - ASCII table for viewing
call_tool('execute_gaql', {..., 'output_format': 'table'})
```
## Tips for Token Efficiency
1. **Filter in code, not queries** - Get data then filter with Python
2. **Use pagination** - Set `'auto_paginate': True` for large result sets
3. **Specify metrics** - Only request the metrics you need
4. **Process before returning** - Aggregate/transform data before logging
5. **Use segments wisely** - Segment only by relevant dimensions
## Troubleshooting
**"Missing required Google Ads credentials"**
- Verify all 5 environment variables are set
- Check for typos in variable names
**"GAQL query failed"**
- Check GAQL syntax with `call_tool('gaql_help', {})`
- Verify customer_id is correct
- Test query in Google Ads API explorer first
**"No results"**
- Verify date range has data
- Check filters are correct
- Try without filters first to debug