MCPGoogleAds by blievens89 - MCP Server

Google Ads MCP Server

Comprehensive Model Context Protocol (MCP) server for Google Ads API integration with Claude. Supports campaigns, ad groups, ads, keywords, audiences, extensions, shopping, and performance analytics.

This implementation follows Anthropic's token-efficiency recommendations by exposing a unified call_tool interface instead of individual tool definitions. This reduces token usage by ~98.7% compared to traditional tool approaches.

Supported Features

📊 Resource Management - List and query campaigns, ad groups, ads, keywords, extensions, audiences, labels, and bidding strategies
🔍 Custom Queries - Execute GAQL (Google Ads Query Language) queries with pagination support
📈 Performance Analytics - Get detailed performance metrics at any level (account, campaign, ad group, ad, keyword)
📋 GAQL Help - Built-in reference for GAQL syntax, fields, filters, and best practices
🎯 Multiple Output Formats - JSON, CSV, and table formats for query results
🛍️ Shopping Support - Query product groups and shopping campaign data
📱 Multi-Channel - Search, Display, YouTube, Shopping, and Performance Max campaigns

How It Works

Instead of listing all tool definitions upfront:

❌ Traditional: 150,000 tokens for all tool definitions + results

Claude writes code to call tools dynamically:

✅ Efficient: 2,000 tokens - only loads what's needed
# List campaigns and filter them
campaigns = call_tool('list_campaigns', {'customer_id': '1234567890'})
active = [c for c in campaigns if c.get('campaign', {}).get('status') == 'ENABLED']

# Get performance with filtering in code
perf = call_tool('get_performance', {
    'level': 'keyword',
    'customer_id': '1234567890',
    'date_range': 'LAST_30_DAYS',
    'metrics': ['clicks', 'conversions', 'cost_micros']
})
high_performers = [k for k in perf if k.get('metrics', {}).get('clicks', 0) > 100]

Setup

1. Install Dependencies

pip install mcp google-ads

2. Configure Credentials

Create a .env file (copy from .env.example) with your Google Ads API credentials:

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

Important: Never commit credentials to git. Use environment variables or .env files with proper .gitignore rules.

3. Add to Claude Desktop

Edit ~/.config/claude/claude_desktop_config.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"
      }
    }
  }
}

Available Operations

📋 List Resources

list_accounts() - List accessible customer accounts
list_campaigns(customer_id) - List all campaigns with budget info
list_ad_groups(customer_id, campaign_id?) - List ad groups (optionally filtered by campaign)
list_ads(customer_id, ad_group_id?) - List ads (optionally filtered by ad group)
list_keywords(customer_id, ad_group_id?) - List keywords with quality scores
list_extensions(customer_id) - List sitelinks, callouts, structured snippets, etc.
list_audiences(customer_id) - List all audiences (remarketing, custom intent, affinity)
list_labels(customer_id) - List custom labels
list_bidding_strategies(customer_id) - List available bidding strategies

🔍 Query Data

execute_gaql(query, customer_id?, output_format?, auto_paginate?, max_pages?)

Execute custom GAQL queries with full pagination support.

# Example: Find high-performance keywords
result = call_tool('execute_gaql', {
    'query': '''SELECT ad_group_criterion.keyword.text, metrics.quality_score, 
                metrics.conversions FROM ad_group_criterion 
                WHERE metrics.quality_score >= 8 AND metrics.conversions > 0''',
    'customer_id': '1234567890',
    'output_format': 'json',
    'auto_paginate': True
})

# Example: Get campaign performance for date range
result = call_tool('execute_gaql', {
    'query': '''SELECT campaign.name, metrics.clicks, metrics.conversions, 
                metrics.cost_micros FROM campaign 
                WHERE segments.date DURING LAST_30_DAYS''',
    'customer_id': '1234567890'
})

Output Formats: json, csv, table

📈 Performance Analytics

get_performance(level, customer_id?, date_range?, days?, metrics?, segments?, filters?, output_format?)

Get detailed performance metrics at any level with flexible filtering and segmentation.

Levels: account, campaign, ad_group, ad, keyword

Date ranges: LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, LAST_QUARTER, LAST_YEAR

Common metrics: impressions, clicks, conversions, cost_micros, ctr, conversion_rate, quality_score

Common segments: date, device, geo_target_country, age_range, gender, day_of_week

# Campaign performance by device
result = call_tool('get_performance', {
    'level': 'campaign',
    'customer_id': '1234567890',
    'date_range': 'LAST_30_DAYS',
    'metrics': ['clicks', 'conversions', 'cost_micros', 'conversion_rate'],
    'segments': ['device', 'geo_target_country'],
    'output_format': 'json'
})

# Keyword analysis for specific campaign
result = call_tool('get_performance', {
    'level': 'keyword',
    'customer_id': '1234567890',
    'date_range': 'LAST_7_DAYS',
    'metrics': ['quality_score', 'impressions', 'clicks', 'conversions'],
    'filters': {'campaign.id': '123456'}
})

# Custom filter - high spend keywords
result = call_tool('get_performance', {
    'level': 'keyword',
    'customer_id': '1234567890',
    'metrics': ['cost_micros', 'conversions'],
    'filters': {'metrics.cost_micros': {'operator': 'GREATER_THAN', 'value': 5000000}}
})

❓ Help & Discovery

gaql_help(topic?, search?)

Get GAQL syntax help and examples.

Topics: overview, resources, metrics, segments, filters, best_practices

# Get help on GAQL filters
help_text = call_tool('gaql_help', {'topic': 'filters'})

# Search for metrics help
result = call_tool('gaql_help', {'search': 'conversion'})

# Get all available help
all_help = call_tool('gaql_help', {})

search_tools(query?)

Search for available resources and operations.

# List all resources
resources = call_tool('search_tools', {})

# Search for shopping-related resources
shopping = call_tool('search_tools', {'query': 'shopping'})

# Find performance metrics operations
perf = call_tool('search_tools', {'query': 'performance'})

Usage Examples

Find campaigns with low CTR

campaigns = call_tool('get_performance', {
    'level': 'campaign',
    'customer_id': '1234567890',
    'date_range': 'LAST_30_DAYS',
    'metrics': ['impressions', 'clicks', 'ctr']
})

# Filter in code - campaigns with CTR < 2%
low_ctr = [c for c in campaigns if c.get('metrics', {}).get('ctr', 0) < 0.02]
print(f"Found {len(low_ctr)} campaigns with low CTR")

Analyze keyword quality

keywords = call_tool('execute_gaql', {
    'query': '''SELECT ad_group_criterion.keyword.text, metrics.quality_score, 
                metrics.impressions FROM ad_group_criterion 
                WHERE metrics.quality_score < 5 AND metrics.impressions > 100''',
    'customer_id': '1234567890'
})

# Process results - group by score
by_score = {}
for kw in keywords:
    score = kw['ad_group_criterion']['keyword']['quality_score']
    by_score.setdefault(score, []).append(kw)

print(f"Keywords needing improvement: {sum(len(v) for v in by_score.values())}")

Shopping campaign analysis

# Get all shopping campaigns
shopping = call_tool('execute_gaql', {
    'query': '''SELECT campaign.id, campaign.name, metrics.conversions, metrics.cost_micros
                FROM campaign WHERE campaign.advertising_channel_type = 'SHOPPING'
                AND segments.date DURING LAST_30_DAYS''',
    'customer_id': '1234567890'
})

# Calculate ROAS (return on ad spend)
for campaign in shopping:
    cost = campaign['metrics']['cost_micros'] / 1_000_000
    conversions = campaign['metrics']['conversions']
    roas = conversions / cost if cost > 0 else 0
    print(f"{campaign['campaign']['name']}: ROAS = {roas:.2f}")

Display network targeting analysis

# Get placement performance
placements = call_tool('execute_gaql', {
    'query': '''SELECT ad_group_criterion.placement.url, metrics.clicks, 
                metrics.conversions, metrics.cost_micros
                FROM ad_group_criterion
                WHERE ad_group_criterion.type = 'PLACEMENT'
                AND segments.date DURING LAST_30_DAYS''',
    'customer_id': '1234567890'
})

# Filter high-cost low-converting placements
inefficient = [p for p in placements if p['metrics']['conversions'] == 0]

Error Handling

The server includes proper error handling and logging. Errors are caught and returned as structured responses to Claude.

Token Efficiency

This server implements Anthropic's code execution approach for MCP:

Approach	Token Usage	Latency
Traditional tools	~150,000	Slower (many round-trips)
Code execution	~2,000	Faster (batch processing)
Savings	98.7% reduction	~75% faster

By using a unified interface and letting Claude write code:

Tools are discovered on-demand, not loaded upfront
Data is filtered and transformed in the execution environment
Large datasets can be processed without bloating context
Complex workflows execute in fewer steps

See Anthropic's engineering blog for details.

Security

Credentials are loaded from environment variables, never hardcoded
Sensitive data is not logged
Always use HTTPS for API communications (handled by Google Ads SDK)