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)

Google Ads MCP Server

Google Ads MCP Server

Supported Features

How It Works

Setup

1. Install Dependencies

2. Configure Credentials

3. Add to Claude Desktop

Available Operations

📋 List Resources

🔍 Query Data

📈 Performance Analytics

❓ Help & Discovery

Usage Examples

Find campaigns with low CTR

Analyze keyword quality

Shopping campaign analysis

Display network targeting analysis

Error Handling

Token Efficiency

Security

Related Resources

New MCP Servers

MCP directory API