Google Ads MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Ads API integration, enabling AI assistants like Claude, ChatGPT, and Gemini to analyze, manage, and optimize Google Ads campaigns through natural language conversations.

Table of Contents

• Overview

• Features

  • Current Features (v1)

  • Roadmap (v2)

• Quick Start

• Setup & Installation

  • Prerequisites

  • Google Ads API Setup

  • Server Installation

  • AI Integration

• MCP Tool Reference

  • v1 Tools (10 Current Tools)

  • v2 Roadmap (161 Planned Tools)

• Usage Examples

• Configuration

• Architecture

• Troubleshooting

• Advanced Topics

• API Reference

• Contributing

• Security

• License

• Citation

• Support & Resources

Overview

The Google Ads MCP Server transforms how you interact with Google Ads by providing a natural language interface powered by Model Context Protocol. Instead of navigating complex dashboards or writing custom API code, you can analyze campaigns, optimize keywords, and manage budgets through simple conversations with AI assistants.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect with external data sources and tools. This server implements MCP to bridge AI assistants with the Google Ads API.

Key Benefits:

• Natural Language Interface: Ask questions and give commands in plain English

• Multi-Platform Support: Works with Claude Desktop, ChatGPT, Gemini, and other MCP-compatible AI assistants

• Comprehensive Coverage: From basic reporting to advanced campaign management

• Secure: OAuth 2.0 authentication with best-practice credential management

• Extensible: Modular architecture supporting 161 planned tools across 14 functional domains

Features

Current Features (v1)

The current stable release (v1) provides 10 essential tools for Google Ads analysis and management:

Analysis & Reporting

• List all accessible Google Ads accounts

• Campaign performance analysis with filtering and date ranges

• Keyword performance tracking (quality scores, positions, conversions)

• Search terms discovery (actual queries triggering ads)

• Ad group performance metrics

• Google's AI-powered optimization recommendations

Campaign Management

• Update campaign daily budgets

• Pause or enable campaigns

• Execute custom GAQL queries for advanced analysis

Roadmap (v2)

The v2 roadmap expands the server to 161 tools across 14 functional domains, covering approximately 85% of the Google Ads API surface area for campaign management and optimization.

Planned Capabilities:

Total: 161 tools covering end-to-end campaign lifecycle management.

See IMPLEMENTATION_PLAN.md for the complete roadmap.

Quick Start

Get up and running in 5 minutes:

Prerequisites

• Python 3.8 or higher

• Google Ads account with active campaigns

• Google Ads API Developer Token (apply here)

Installation

1. Clone the repository:

   git clone https://github.com/johnoconnor0/google-ads-mcp.git
   cd google-ads-mcp

2. Install dependencies:

   pip install -r requirements.txt

3. Generate OAuth credentials (see Google Ads API Setup for details):

   python generate_refresh_token.py

4. Configure Claude Desktop (or your preferred AI assistant):

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

   {
     "mcpServers": {
       "google-ads": {
         "command": "python",
         "args": ["/absolute/path/to/google_ads_mcp.py"],
         "env": {}
       }
     }
   }

5. Restart Claude Desktop and start asking questions about your Google Ads accounts!

First Steps

Once configured, try these commands in Claude Desktop:

"Initialize my Google Ads connection with these credentials..."
"Show me all my Google Ads accounts"
"Analyze campaign performance for the last 30 days"
"Which keywords have the lowest quality scores?"

See Usage Examples for more.

Setup & Installation

Prerequisites

Required

• Python: Version 3.8 or higher

  python --version  # Should output 3.8 or higher

• Google Ads Account: Active account with campaigns

• Google Ads API Access: Developer token (may take 24-48 hours for approval)

• OAuth 2.0 Credentials: Client ID and Client Secret from Google Cloud Console

Optional

• MCC Account: For managing multiple client accounts

• Redis: For distributed caching (optional, defaults to in-memory cache)

Google Ads API Setup

Step 1: Apply for Developer Token

1. Sign in to your Google Ads account

2. Navigate to Tools & Settings → Setup → API Center

3. Apply for a developer token

4. Wait for approval (typically 24-48 hours)

5. Important: Test developer tokens work immediately but have limitations

Resource: Google Ads API Developer Token Guide

Step 2: Create OAuth 2.0 Credentials

1. Go to Google Cloud Console

2. Create a new project (or select existing)

3. Enable the Google Ads API:

   • Navigation → APIs & Services → Library

   • Search for "Google Ads API"

   • Click "Enable"

4. Create OAuth credentials:

   • APIs & Services → Credentials

   • Click Create Credentials → OAuth client ID

   • Choose Desktop app as application type

   • Name your OAuth client (e.g., "Google Ads MCP Server")

   • Click Create

5. Download your credentials or copy:

   • Client ID (ends with .apps.googleusercontent.com)

   • Client Secret

Resource: OAuth 2.0 Setup Guide

Step 3: Generate Refresh Token

Use the provided utility script to generate a refresh token:

python generate_refresh_token.py

What this script does:

1. Opens a browser for Google authorization

2. You grant access to your Google Ads account

3. Generates a refresh token (long-lived credential)

4. Displays the refresh token to copy

Alternative manual method:

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_ID = 'your-client-id.apps.googleusercontent.com'
CLIENT_SECRET = 'your-client-secret'
SCOPES = ['https://www.googleapis.com/auth/adwords']

flow = InstalledAppFlow.from_client_config(
    {
        "installed": {
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    },
    scopes=SCOPES
)

credentials = flow.run_local_server(port=0)
print(f"Refresh Token: {credentials.refresh_token}")

Important: Store your refresh token securely! It provides ongoing access to your Google Ads account.

Server Installation

Install Python Dependencies

Option 1: Install from requirements.txt (recommended):

pip install -r requirements.txt

Option 2: Manual installation:

pip install google-ads>=25.0.0 mcp>=1.1.0 httpx>=0.27.0 pydantic>=2.0.0 google-auth-oauthlib>=1.0.0

Optional dependencies (for advanced features):

# Caching with Redis
pip install redis>=5.0.0

# Export and reporting
pip install openpyxl>=3.1.2 reportlab>=4.0.0 matplotlib>=3.8.0

Verify Installation

python -c "import google.ads.googleads, mcp, httpx, pydantic; print('All dependencies installed successfully!')"

AI Integration

The Google Ads MCP Server can be integrated with multiple AI platforms:

Claude Desktop Integration

Recommended for: Most users, easiest setup

1. Locate configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add MCP server configuration:

   {
     "mcpServers": {
       "google-ads": {
         "command": "python",
         "args": ["/absolute/path/to/google_ads_mcp.py"],
         "env": {}
       }
     }
   }

   Replace /absolute/path/to/google_ads_mcp.py with the actual file path.

3. Restart Claude Desktop for changes to take effect

4. Initialize the connection in Claude:

   Initialize my Google Ads connection with these credentials:
   - Developer Token: YOUR_DEV_TOKEN
   - Client ID: YOUR_CLIENT_ID.apps.googleusercontent.com
   - Client Secret: YOUR_CLIENT_SECRET
   - Refresh Token: YOUR_REFRESH_TOKEN
   - Login Customer ID: YOUR_MCC_ID (optional, only if using MCC)

Resources:

• Claude Desktop MCP Documentation

• QUICKSTART.md

ChatGPT Integration

Status: Experimental (MCP support via third-party tools)

ChatGPT does not natively support MCP as of December 2025. However, integration is possible via:

Option 1: MCP Bridge (if available)

• Use an MCP-to-OpenAI API bridge

• Configure the bridge to expose Google Ads MCP tools as OpenAI functions

• Access via ChatGPT Plus with plugin support

Option 2: Custom GPT with API Wrapper

• Create a web API wrapper around the MCP server

• Build a Custom GPT with function calling to your API

• Configure authentication and endpoints

Option 3: Use Claude Code or API

• Run the MCP server with Claude Code (CLI)

• Use Claude API to access the MCP tools programmatically

• Integrate results into your ChatGPT workflow

Note: As ChatGPT's MCP support evolves, this section will be updated with native integration instructions.

Gemini Integration

Status: Experimental (MCP support via third-party tools)

Google's Gemini does not natively support MCP as of December 2025. However, integration is possible via:

Option 1: Vertex AI Function Calling

• Deploy the MCP server as a Google Cloud Function or Cloud Run service

• Use Vertex AI's function calling with Gemini

• Map MCP tools to Gemini function definitions

Option 2: LangChain Integration

• Use LangChain to create a bridge between Gemini and MCP tools

• Define MCP tools as LangChain tools

• Create a Gemini agent with MCP tool access

Option 3: Custom Integration

• Build a REST API wrapper around the MCP server

• Use Gemini API with function calling

• Map Google Ads operations to function definitions

Resources:

• Vertex AI Function Calling

• Gemini API Documentation

Other MCP-Compatible Platforms

The server works with any MCP-compatible client. See the MCP Documentation for integration guides.

MCP Tool Reference

v1 Tools (10 Current Tools)

The current stable release provides these tools:

1. google_ads_initialize

Description: Initialize API connection with OAuth credentials.

Parameters:

{
  "developer_token": "string (required)",
  "client_id": "string (required)",
  "client_secret": "string (required)",
  "refresh_token": "string (required)",
  "login_customer_id": "string (optional)"
}

Example:

Initialize with:
- Developer Token: abc123...
- Client ID: 123456789.apps.googleusercontent.com
- Client Secret: xyz789...
- Refresh Token: 1//abc...
- Login Customer ID: 1234567890 (only for MCC accounts)

Returns: Confirmation message with API version and accessibility check

2. google_ads_list_accounts

Description: List all accessible Google Ads accounts.

Parameters:

{
  "response_format": "markdown | json (default: markdown)"
}

Example:

"Show me all my Google Ads accounts"
"List accounts in JSON format"

Returns: Account list with customer IDs, names, and descriptive names

3. google_ads_campaign_performance

Description: Get comprehensive campaign metrics with filtering and date ranges.

Parameters:

{
  "customer_id": "string (required, 10 digits no hyphens)",
  "date_range": "TODAY | YESTERDAY | LAST_7_DAYS | LAST_30_DAYS | etc. (default: LAST_30_DAYS)",
  "campaign_status": "ENABLED | PAUSED | REMOVED (optional)",
  "min_cost": "number (optional, in account currency)",
  "limit": "number (default: 50, max: 100)",
  "response_format": "markdown | json (default: markdown)"
}

Example:

"Show campaign performance for the last 30 days for account 1234567890"
"Find campaigns with at least $100 in spend this month"
"Show only enabled campaigns for account 1234567890"

Returns: Campaign metrics including impressions, clicks, cost, conversions, CTR, CPC, conversion rate

4. google_ads_keyword_performance

Description: Analyze keyword-level performance with quality scores and positions.

Parameters:

{
  "customer_id": "string (required)",
  "campaign_id": "string (optional)",
  "date_range": "string (default: LAST_30_DAYS)",
  "min_impressions": "number (optional)",
  "limit": "number (default: 50)",
  "response_format": "markdown | json"
}

Example:

"Analyze keyword performance for campaign 12345"
"Show keywords with quality score below 5"
"Find keywords with the highest cost per conversion"

Returns: Keyword metrics including quality score, average position, impressions, clicks, cost, conversions

5. google_ads_search_terms

Description: Get actual search queries that triggered your ads.

Parameters:

{
  "customer_id": "string (required)",
  "campaign_id": "string (optional)",
  "date_range": "string (default: LAST_30_DAYS)",
  "min_impressions": "number (default: 10)",
  "limit": "number (default: 50)",
  "response_format": "markdown | json"
}

Example:

"What search terms triggered my ads in the last 30 days?"
"Find high-impression search terms with low CTR"
"Show search terms for campaign 67890"

Returns: Search term, match type, impressions, clicks, cost, conversions, CTR

6. google_ads_ad_group_performance

Description: Analyze ad group-level metrics.

Parameters:

{
  "customer_id": "string (required)",
  "campaign_id": "string (optional)",
  "date_range": "string (default: LAST_30_DAYS)",
  "limit": "number (default: 50)",
  "response_format": "markdown | json"
}

Example:

"Show ad group performance for all campaigns"
"Find best-performing ad groups in campaign 12345"

Returns: Ad group metrics including impressions, clicks, cost, conversions, CTR, CPC

7. google_ads_recommendations

Description: Get Google's AI-powered optimization suggestions.

Parameters:

{
  "customer_id": "string (required)",
  "recommendation_types": "array of strings (optional)",
  "limit": "number (default: 20)",
  "response_format": "markdown | json"
}

Example:

"Show optimization recommendations for account 1234567890"
"What does Google suggest for improving my campaigns?"

Returns: Recommendation type, impact estimate, suggested changes, rationale

8. google_ads_update_campaign_budget

Description: Modify campaign daily budget.

Parameters:

{
  "customer_id": "string (required)",
  "campaign_id": "string (required)",
  "budget_amount_micros": "number (required, in micros)"
}

Budget conversion: Multiply your budget by 1,000,000

• $10.00 = 10,000,000 micros

• $50.50 = 50,500,000 micros

• $100.00 = 100,000,000 micros

Example:

"Set campaign 12345 budget to $75 per day"
"Increase budget for campaign 67890 to 100,000,000 micros ($100)"

Returns: Confirmation with old and new budget values

9. google_ads_update_campaign_status

Description: Pause or enable campaigns.

Parameters:

{
  "customer_id": "string (required)",
  "campaign_id": "string (required)",
  "status": "ENABLED | PAUSED (required)"
}

Example:

"Pause campaign 12345"
"Enable campaign 67890"

Returns: Confirmation with new status

10. google_ads_custom_query

Description: Execute custom GAQL (Google Ads Query Language) queries.

Parameters:

{
  "customer_id": "string (required)",
  "query": "string (required, valid GAQL query)",
  "response_format": "markdown | json"
}

Example:

"Execute this GAQL query: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000"

Resources:

• GAQL Query Builder

• GAQL Documentation

Returns: Query results in requested format

v2 Roadmap (161 Planned Tools)

The v2 implementation expands the server to 161 tools across 14 domains. Below is a summary of planned capabilities.

Campaign Management (23 tools)

Creation & Configuration:

• Create campaigns (all 9 types: Search, Display, Shopping, Video, Performance Max, App, Local, Smart, Demand Gen)

• Configure networks, locations, languages, start/end dates

• Set up budgets (standard, shared, portfolio)

• Configure bidding strategies

Updates & Optimization:

• Modify campaign settings (name, networks, targeting)

• Update location and language targeting

• Manage device bid adjustments

• Configure ad scheduling (dayparting)

• Add campaign-level exclusions

Management:

• Campaign experiments and A/B testing

• Campaign labels and organization

• Campaign deletion and archival

Status: Priority 2 - In active development

Ad & Creative Management (18 tools)

Ad Creation:

• Responsive Search Ads (RSA) - up to 15 headlines, 4 descriptions

• Expanded Text Ads (legacy)

• Responsive Display Ads

• Image ads (Display Network)

• Video ads (YouTube, TrueView)

• Performance Max asset groups

Ad Optimization:

• Ad copy testing and analysis

• Ad strength tracking

• Creative asset management

• Ad preview and testing

Status: Priority 2 - Planned

Keyword Management (15 tools)

Keyword Operations:

• Bulk keyword addition (CSV import)

• Keyword updates (match types, bids, status)

• Keyword deletion

• Negative keyword management

• Negative keyword lists (shared)

Keyword Research & Analysis:

• Keyword forecasting

• Keyword suggestions

• Match type optimization

• Quality score tracking and improvement

Status: Priority 2 - Planned

Bidding & Optimization (12 tools)

Bidding Strategies:

• Portfolio bidding strategies (Target CPA, Target ROAS, Maximize Conversions)

• Bid adjustments (device, location, demographics, audiences, time-of-day)

• Manual bidding configuration

• Smart Bidding setup and monitoring

Optimization:

• Automated rules and triggers

• Bid simulation and forecasting

• Performance optimization suggestions

Status: Priority 2 - Planned

Audience Management (14 tools)

Audience Creation:

• Remarketing lists

• Customer Match audience uploads

• Custom audiences (interests, behaviors)

• Similar audiences (lookalikes)

• In-market and affinity audiences

Audience Targeting:

• Apply audiences to campaigns/ad groups

• Audience bid adjustments

• Exclusion lists

• Audience performance tracking

Status: Priority 3 - Planned

Conversion Tracking (11 tools)

Setup & Configuration:

• Create conversion actions

• Configure conversion tracking tags

• Import offline conversions

• Set up call tracking

Attribution & Analysis:

• Multi-touch attribution models

• Conversion value rules

• Conversion lift studies

• Cross-device conversion tracking

Status: Priority 3 - Planned

Advanced Reporting (25 tools)

Specialized Reports:

• Geographic performance (country, region, city, postal code)

• Demographic reports (age, gender, household income)

• Time-based analysis (hour of day, day of week)

• Device performance breakdown

• Auction insights (competitive analysis)

• Landing page performance

• Call metrics and call tracking

• Video performance (YouTube)

• Shopping performance (product groups)

Report Customization:

• Custom report builder

• Period-over-period comparison

• Trend analysis

• Export to Excel/PDF/CSV

• Scheduled reports

Status: Priority 2-3 - Partially planned

Batch Operations (8 tools)

Bulk Operations:

• Batch campaign creation

• Bulk keyword uploads (CSV)

• Mass ad group creation

• Bulk status changes

• Batch budget updates

Import/Export:

• Google Ads Editor CSV import

• Export campaigns to CSV

• Bulk change history

Status: Priority 3 - Planned

Extensions & Assets (12 tools)

Extension Types:

• Sitelink extensions

• Callout extensions

• Call extensions

• Location extensions

• Price extensions

• Structured snippet extensions

• Promotion extensions

• App extensions

Management:

• Extension performance tracking

• Asset library management

• Extension scheduling

• Extension bid adjustments

Status: Priority 3 - Planned

Shopping & Performance Max (10 tools)

Shopping Campaigns:

• Product feed management

• Product group creation

• Shopping campaign optimization

• Merchant Center integration

Performance Max:

• Asset group creation

• Audience signals

• Performance tracking

• Budget optimization

Status: Priority 3 - Planned

Local & App Campaigns (8 tools)

Local Campaigns:

• Store visits tracking

• Local inventory ads

• Location-based bidding

• Call tracking

App Campaigns:

• App install campaigns

• App engagement campaigns

• Deep link configuration

• In-app event tracking

Status: Priority 3 - Planned

Automation (10 tools)

Automated Rules:

• Create custom rules

• Schedule automated tasks

• Trigger-based actions

• Rule performance tracking

Smart Features:

• Smart Bidding automation

• Automated extensions

• Dynamic ad customization

• AI-powered optimization

Status: Priority 3 - Planned

Insights & Analytics (8 tools)

Forecasting:

• Budget forecasting

• Conversion forecasting

• Seasonal trend analysis

• Growth projections

Competitive Analysis:

• Auction insights

• Competitive benchmarking

• Market share analysis

Change History:

• Account change log

• Performance change attribution

• Rollback capabilities

Status: Priority 3 - Planned

Labels & Organization (7 tools)

Labels:

• Campaign labels

• Ad group labels

• Keyword labels

• Ad labels

Organization:

• Folder structure management

• Resource organization

• Bulk label operations

Status: Priority 3 - Planned

For the complete implementation plan with technical details, see IMPLEMENTATION_PLAN.md.

Usage Examples

Claude Desktop Conversations

Account Overview

User: "Show me all my Google Ads accounts"

Claude: [Calls google_ads_list_accounts]
I can see you have 3 accessible Google Ads accounts:
1. Account 123-456-7890 (My Business)
2. Account 234-567-8901 (E-commerce Store)
3. Account 345-678-9012 (Client ABC)

Campaign Analysis

User: "Analyze campaign performance for the last 30 days for my main account"

Claude: [Calls google_ads_campaign_performance with customer_id="1234567890"]
Here's the performance for your campaigns over the last 30 days:

Top Performers:
- Brand Campaign: $1,245 spent, 523 conversions, $2.38 CPA
- Shopping Campaign: $2,100 spent, 312 conversions, $6.73 CPA

Needs Attention:
- Generic Keywords: $850 spent, 12 conversions, $70.83 CPA (consider pausing)

Keyword Optimization

User: "Show me keywords with quality score below 5 for campaign 12345"

Claude: [Calls google_ads_keyword_performance with filtering]
Found 8 keywords with quality scores below 5:

1. "cheap widgets" - QS: 3, Avg Pos: 4.2, $145 spent
   Suggestion: Improve ad relevance or pause
2. "buy widgets online" - QS: 4, Avg Pos: 3.8, $98 spent
   Suggestion: Create dedicated ad group with tailored ad copy
...

Budget Management

User: "Increase the budget for campaign 67890 to $150 per day"

Claude: [Calls google_ads_update_campaign_budget with budget_amount_micros=150000000]
Budget updated successfully:
- Campaign: Summer Sale 2025
- Old Budget: $100.00/day
- New Budget: $150.00/day
- Effective: Immediately

Search Terms Discovery

User: "What search terms are triggering my ads with high impressions but low CTR?"

Claude: [Calls google_ads_search_terms with analysis]
Found 15 search terms with >1000 impressions and CTR <1%:

High Priority:
1. "free widgets" - 5,234 impressions, 0.3% CTR
   Recommendation: Add as negative keyword
2. "how to make widgets" - 3,421 impressions, 0.5% CTR
   Recommendation: Add as negative keyword (informational intent)

Programmatic Usage

If integrating directly with the MCP server programmatically:

from mcp import ClientSession
import asyncio

async def analyze_campaigns():
    async with ClientSession() as session:
        # Initialize connection
        await session.call_tool("google_ads_initialize", {
            "developer_token": "YOUR_TOKEN",
            "client_id": "YOUR_CLIENT_ID",
            "client_secret": "YOUR_SECRET",
            "refresh_token": "YOUR_REFRESH_TOKEN"
        })

        # Get campaign performance
        result = await session.call_tool("google_ads_campaign_performance", {
            "customer_id": "1234567890",
            "date_range": "LAST_7_DAYS",
            "response_format": "json"
        })

        print(result)

asyncio.run(analyze_campaigns())

Configuration

Configuration File (config.yaml)

The v2 server supports configuration via YAML files:

authentication:
  method: oauth2  # or service_account
  developer_token: ${GOOGLE_ADS_DEVELOPER_TOKEN}
  client_id: ${GOOGLE_ADS_CLIENT_ID}
  client_secret: ${GOOGLE_ADS_CLIENT_SECRET}
  refresh_token: ${GOOGLE_ADS_REFRESH_TOKEN}
  login_customer_id: ${GOOGLE_ADS_LOGIN_CUSTOMER_ID}  # Optional MCC

performance:
  cache:
    backend: memory  # Options: memory, redis, none
    ttl:
      accounts: 3600      # 1 hour
      campaigns: 300      # 5 minutes
      keywords: 300       # 5 minutes
      search_terms: 600   # 10 minutes
    redis_url: redis://localhost:6379/0  # If using Redis
    max_size: 1000  # For memory cache

  connection_pool:
    size: 10
    timeout: 30

  rate_limiting:
    enabled: true
    requests_per_minute: 60
    burst_size: 10

error_handling:
  retry:
    enabled: true
    max_attempts: 3
    backoff_strategy: exponential  # linear, exponential
    initial_delay: 1
    max_delay: 30

  alerts:
    webhook_url: https://your-webhook.com/alerts
    email: admin@example.com

  log_errors: true

logging:
  level: INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
  format: json  # json, text
  file: /var/log/google-mcp/server.log
  console: true

features:
  batch_operations: true
  auto_recommendations: true
  advanced_reporting: true
  conversion_tracking: true
  audience_management: true

api_version: v17  # Google Ads API version
default_page_size: 50
character_limit: 25000  # MCP response size limit

Environment Variables

Override configuration with environment variables:

# Authentication
export GOOGLE_ADS_DEVELOPER_TOKEN="your-token"
export GOOGLE_ADS_CLIENT_ID="your-client-id"
export GOOGLE_ADS_CLIENT_SECRET="your-secret"
export GOOGLE_ADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="1234567890"  # Optional

# Performance
export GOOGLE_MCP_CACHE_BACKEND="redis"
export GOOGLE_MCP_REDIS_URL="redis://localhost:6379/0"

# Logging
export GOOGLE_MCP_LOG_LEVEL="DEBUG"
export GOOGLE_MCP_LOG_FILE="/var/log/google-mcp.log"

Feature Flags

Enable or disable features:

features:
  batch_operations: true      # Bulk operations support
  auto_recommendations: true  # Google AI recommendations
  advanced_reporting: true    # 25+ specialized reports
  conversion_tracking: true   # Conversion management
  audience_management: true   # Remarketing, Customer Match

Caching Options

Memory Cache (default, no setup required):

• Fast, in-process caching

• No external dependencies

• Limited to single process

Redis Cache (recommended for production):

• Distributed caching across processes

• Persistent cache across restarts

• Supports clustering

No Cache:

• Disable caching for testing or debugging

Architecture

Project Structure

google-mcp/
├── google_ads_mcp.py              # Main MCP server (v1) - 10 tools
├── google_ads_mcp_v2.py           # Enhanced server (v2) - 161 planned tools
├── generate_refresh_token.py      # OAuth token generation utility
│
├── Infrastructure Managers
├── auth_manager.py                # OAuth authentication & token management
├── config_manager.py              # Configuration loading (YAML/JSON)
├── cache_manager.py               # Caching layer (Memory/Redis)
├── error_handler.py               # Error handling & retry logic
├── logger.py                      # Structured logging
├── response_handler.py            # Response formatting & streaming
├── query_optimizer.py             # GAQL query optimization
│
├── Domain Managers
├── campaign_manager.py            # Campaign creation & management
├── ad_group_manager.py            # Ad group operations
├── ad_manager.py                  # Ad creation & management
├── keyword_manager.py             # Keyword operations
├── bidding_strategy_manager.py    # Bidding strategy configuration
├── audience_manager.py            # Audience management
├── conversion_manager.py          # Conversion tracking
├── automation_manager.py          # Automated rules
├── batch_operations_manager.py    # Bulk operations
├── extensions_manager.py          # Ad extensions
├── labels_manager.py              # Label management
├── shopping_pmax_manager.py       # Shopping & Performance Max
├── local_app_manager.py           # Local & app campaigns
├── insights_manager.py            # Analytics & insights
├── reporting_manager.py           # Advanced reporting
│
├── MCP Tool Registrations
├── mcp_tools_campaigns.py         # Campaign tools
├── mcp_tools_ad_groups.py         # Ad group tools
├── mcp_tools_ads.py               # Ad tools
├── mcp_tools_keywords.py          # Keyword tools
├── mcp_tools_bidding.py           # Bidding tools
├── mcp_tools_audiences.py         # Audience tools
├── mcp_tools_conversions.py       # Conversion tools
├── mcp_tools_automation.py        # Automation tools
├── mcp_tools_batch.py             # Batch operation tools
├── mcp_tools_extensions.py        # Extension tools
├── mcp_tools_shopping_pmax.py     # Shopping/PMax tools
├── mcp_tools_local_app.py         # Local/App tools
├── mcp_tools_insights.py          # Insights tools
├── mcp_tools_reporting.py         # Reporting tools
│
├── Configuration
├── config.yaml                    # Server configuration
├── config.example.yaml            # Configuration template
├── requirements.txt               # Python dependencies
│
├── Documentation
├── README.md                      # This file
├── SECURITY.md                    # Security policy
├── CONTRIBUTING.md                # Contribution guidelines
├── LICENSE                        # MIT License
├── CITATION.cff                   # Citation information
├── CODEOWNERS                     # Code ownership
├── documentation/                 # Additional documentation
│   ├── QUICKSTART.md
│   ├── IMPLEMENTATION_PLAN.md
│   ├── EXECUTIVE_SUMMARY.md
│   └── ...
│
└── .claude/                       # Claude Code configuration
    ├── claude_project.json
    └── CLAUDE.md

Manager Module Pattern

Each domain manager follows this pattern:

class CampaignManager:
    """Handles campaign-related operations."""

    def __init__(self, client: GoogleAdsClient, config: Config):
        self.client = client
        self.config = config

    def create_campaign(...) -> dict:
        """Create a new campaign."""
        # Validation
        # API operation
        # Error handling
        # Response formatting

MCP Tool Registration System

Tools are registered using FastMCP:

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel

mcp = FastMCP("google_ads_mcp")

@mcp.tool()
def google_ads_create_campaign(request: CampaignCreateRequest) -> dict:
    """Create a new Google Ads campaign."""
    manager = CampaignManager(client, config)
    return manager.create_campaign(**request.dict())

Data Flow

1. AI Assistant sends natural language request

2. MCP Server receives tool call with parameters

3. Manager Module validates input and executes API operation

4. Google Ads API processes the request

5. Response Handler formats the result (Markdown/JSON)

6. MCP Server returns the formatted response

7. AI Assistant presents the result to the user

Troubleshooting

Common Errors

"Client not initialized" Error

Cause: The Google Ads client hasn't been initialized with credentials.

Solution:

Initialize my Google Ads connection with these credentials:
- Developer Token: YOUR_TOKEN
- Client ID: YOUR_CLIENT_ID
- Client Secret: YOUR_SECRET
- Refresh Token: YOUR_REFRESH_TOKEN

"Invalid customer ID" Error

Cause: Customer ID format is incorrect.

Solution: Ensure customer IDs are:

• 10 digits

• Without hyphens

• Example: 1234567890 (correct), 123-456-7890 (wrong)

"Authentication failed" Error

Causes and solutions:

1. Developer token invalid:

   • Verify token in Google Ads API Center

   • Ensure token is approved (not test-only)

2. OAuth credentials incorrect:

   • Regenerate refresh token

   • Verify Client ID and Client Secret

3. Token expired:

   • Refresh tokens can expire after prolonged inactivity

   • Generate a new refresh token

4. Wrong login_customer_id:

   • Only use login_customer_id for MCC accounts

   • Verify the MCC ID is correct

"Insufficient permissions" Error

Causes:

• Your Google account doesn't have access to the Google Ads account

• Developer token has limited access level

• OAuth scope doesn't include Google Ads API

Solution:

1. Verify account access in Google Ads

2. Ensure OAuth scope is https://www.googleapis.com/auth/adwords

3. Check developer token access level

Rate Limiting

Cause: Exceeded Google Ads API rate limits.

Solutions:

• Reduce request frequency

• Use smaller date ranges

• Enable caching (Memory or Redis)

• Implement request throttling

Google Ads API Limits:

• 15,000 operations per day (test accounts)

• Higher limits for production accounts

• Contact Google for increased limits

Debug Logging

Enable debug logging for troubleshooting:

v1 (google_ads_mcp.py):

import logging
logging.basicConfig(level=logging.DEBUG)

v2 (config.yaml):

logging:
  level: DEBUG
  console: true
  file: /tmp/google-mcp-debug.log

Testing Connections

Test your setup manually:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "developer_token": "YOUR_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "use_proto_plus": True
}

client = GoogleAdsClient.load_from_dict(credentials)
customer_service = client.get_service("CustomerService")
accessible_customers = customer_service.list_accessible_customers()
print(f"Accessible customers: {accessible_customers.resource_names}")

Getting Help

If you're still stuck:

1. Check existing issues: GitHub Issues

2. Review documentation: Google Ads API Docs

3. Create an issue: Provide error messages, logs, and steps to reproduce

4. Contact support: See Support & Resources

Advanced Topics

Multi-Account (MCC) Management

What is MCC?

MCC (My Client Center) is a Google Ads manager account that lets you manage multiple client accounts from a single interface.

Setup:

1. Create an MCC account at ads.google.com/mcc

2. Link client accounts to your MCC

3. Use MCC customer ID as login_customer_id during initialization

Usage:

Initialize with:
- Login Customer ID: 1234567890 (your MCC ID)
- ...other credentials...

Then access client accounts:
"Analyze campaigns for client account 2345678901"
"List all accounts under my MCC"

Benefits:

• Single authentication for multiple accounts

• Centralized reporting across clients

• Efficient bulk operations

Performance Optimization

Caching Strategies:

1. Memory Cache: Fast, but limited to single process

2. Redis Cache: Distributed, persistent, recommended for production

3. Selective Caching: Cache expensive queries, refresh on mutations

Best Practices:

• Use date range filters to reduce data volume

• Apply limit parameters to control result size

• Enable caching for frequently accessed data

• Use batch operations for bulk changes

Custom GAQL Queries

GAQL (Google Ads Query Language) enables advanced custom queries.

Query Structure:

SELECT
  resource.field1,
  resource.field2,
  metrics.metric1
FROM resource_name
WHERE conditions
ORDER BY field
LIMIT n

Example - Find top-performing keywords:

SELECT
  ad_group_criterion.keyword.text,
  metrics.clicks,
  metrics.conversions,
  metrics.cost_micros
FROM keyword_view
WHERE
  metrics.impressions > 100
  AND campaign.status = 'ENABLED'
ORDER BY metrics.conversions DESC
LIMIT 20

Resources:

• Query Builder

• Query Validator

• GAQL Grammar

Batch Operations

Efficiently make bulk changes using batch operations (v2 feature):

Benefits:

• Reduce API calls (1 batch vs. 100 individual calls)

• Faster execution

• Lower quota usage

Use Cases:

• Bulk keyword uploads

• Mass campaign creation

• Batch budget updates

• Bulk status changes

API Reference

Google Ads API

• Documentation: Google Ads API Docs

• Reference: API Reference

• Field Guide: Field Reference

• Release Notes: What's New

GAQL Resources

• Query Builder: Interactive Query Builder

• Query Validator: Validate Queries

• Query Grammar: GAQL Grammar Reference

MCP Protocol

• Specification: MCP Specification

• Documentation: MCP Docs

• GitHub: MCP GitHub

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Ways to contribute:

• Report bugs or request features via GitHub Issues

• Submit pull requests for bug fixes or new features

• Improve documentation

• Share usage examples and tips

Development workflow:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test thoroughly

5. Submit a pull request

See CONTRIBUTING.md for detailed instructions.

Security

Security is a top priority. Please see SECURITY.md for:

• Security policy and supported versions

• How to report vulnerabilities

• Security best practices

• Credential management guidelines

Quick security tips:

• Never commit credentials to version control

• Use environment variables for secrets

• Rotate OAuth tokens regularly

• Enable 2FA on Google Ads accounts

• Monitor API access logs

License

This project is licensed under the MIT License. See LICENSE for details.

MIT License

Copyright (c) 2025 John O'Connor

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

Citation

If you use this software in your research or project, please cite it:

APA Format:

O'Connor, J. (2025). Google Ads MCP Server (Version 1.0.0) [Computer software].
https://github.com/johnoconnor0/google-ads-mcp

BibTeX:

@software{oconnor_google_mcp_2025,
  author = {O'Connor, John},
  title = {Google Ads MCP Server},
  year = {2025},
  version = {1.0.0},
  url = {https://github.com/johnoconnor0/google-ads-mcp}
}

See CITATION.cff for machine-readable citation metadata.

Support & Resources

Documentation

• Quick Start: QUICKSTART.md

• Implementation Plan: IMPLEMENTATION_PLAN.md

• Executive Summary: EXECUTIVE_SUMMARY.md

• Claude Instructions: .claude/CLAUDE.md

Google Ads Resources

• Google Ads API: Documentation

• Developer Token: Apply Here

• OAuth Setup: OAuth Guide

• Support: Google Ads API Support

MCP Resources

• MCP Documentation: modelcontextprotocol.io

• Claude Desktop: Claude Desktop Docs

• MCP GitHub: github.com/modelcontextprotocol

Community & Support

• GitHub Issues: Report issues or request features

• Discussions: GitHub Discussions

• Email: open-source@weblifter.com.au

Related Projects

• Claude Desktop: AI assistant with MCP support

• MCP Servers: Awesome MCP Servers

• Google Ads Scripts: Scripts Library

Version: 1.0.0 Last Updated: December 17, 2025 Author: John O'Connor License: MIT

Star this repository if you find it useful!