MCP 服务器

Google Ads MCP Server

Enables comprehensive Google Ads campaign management and analysis through natural language, including performance metrics, keyword optimization, budget management, and custom GAQL queries.

README

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.

Overview
Features
- Current Features (v1)
- Roadmap (v2)
Quick Start
Setup & Installation
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:

Domain	Tools	Description
Campaign Management	23	Create, update, delete campaigns (all 9 types)
Ad & Creative Management	18	Responsive Search Ads, Display, Video, Performance Max
Keyword Management	15	Bulk operations, negative keywords, match types
Bidding & Optimization	12	Portfolio strategies, bid adjustments, automation
Audience Management	14	Remarketing, Customer Match, custom audiences
Conversion Tracking	11	Setup, offline imports, attribution
Advanced Reporting	25	Geographic, demographic, competitive insights
Batch Operations	8	Bulk uploads, mass updates, CSV import/export
Extensions & Assets	12	Sitelinks, callouts, structured snippets
Shopping & PMax	10	Product feeds, Performance Max campaigns
Local & App Campaigns	8	Store visits, app installs, local inventory
Automation	10	Automated rules, smart bidding, scripts integration
Insights & Analytics	8	Forecasting, auction insights, change history
Labels & Organization	7	Campaign labels, asset groups, organization

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

Clone the repository:

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

Install dependencies:
```
pip install -r requirements.txt
```
Generate OAuth credentials (see Google Ads API Setup for details):
```
python generate_refresh_token.py
```

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": {}
    }
  }
}

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

Sign in to your Google Ads account
Navigate to Tools & Settings → Setup → API Center
Apply for a developer token
Wait for approval (typically 24-48 hours)
Important: Test developer tokens work immediately but have limitations

Resource: Google Ads API Developer Token Guide

Step 2: Create OAuth 2.0 Credentials

Go to Google Cloud Console
Create a new project (or select existing)
Enable the Google Ads API:
- Navigation → APIs & Services → Library
- Search for "Google Ads API"
- Click "Enable"
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
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:

Opens a browser for Google authorization
You grant access to your Google Ads account
Generates a refresh token (long-lived credential)
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

Locate configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

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.

Restart Claude Desktop for changes to take effect

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:

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:

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:

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

AI Assistant sends natural language request
MCP Server receives tool call with parameters
Manager Module validates input and executes API operation
Google Ads API processes the request
Response Handler formats the result (Markdown/JSON)
MCP Server returns the formatted response
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:

Developer token invalid:
- Verify token in Google Ads API Center
- Ensure token is approved (not test-only)
OAuth credentials incorrect:
- Regenerate refresh token
- Verify Client ID and Client Secret
Token expired:
- Refresh tokens can expire after prolonged inactivity
- Generate a new refresh token
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:

Verify account access in Google Ads
Ensure OAuth scope is https://www.googleapis.com/auth/adwords
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:

Check existing issues: GitHub Issues
Review documentation: Google Ads API Docs
Create an issue: Provide error messages, logs, and steps to reproduce
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:

Create an MCC account at ads.google.com/mcc
Link client accounts to your MCC
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:

Memory Cache: Fast, but limited to single process
Redis Cache: Distributed, persistent, recommended for production
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:

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:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
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!

Google Ads MCP Server

README

Google Ads MCP Server

Table of Contents

Overview

Features

Current Features (v1)

Roadmap (v2)

Quick Start

Prerequisites

Installation

First Steps

Setup & Installation

Prerequisites

Required

Optional

Google Ads API Setup

Step 1: Apply for Developer Token

Step 2: Create OAuth 2.0 Credentials

Step 3: Generate Refresh Token

Server Installation

Install Python Dependencies

Verify Installation

AI Integration

Claude Desktop Integration

ChatGPT Integration

Gemini Integration

Other MCP-Compatible Platforms

MCP Tool Reference

v1 Tools (10 Current Tools)

1. google_ads_initialize

2. google_ads_list_accounts

3. google_ads_campaign_performance

4. google_ads_keyword_performance

5. google_ads_search_terms

6. google_ads_ad_group_performance

7. google_ads_recommendations

8. google_ads_update_campaign_budget

9. google_ads_update_campaign_status

10. google_ads_custom_query

v2 Roadmap (161 Planned Tools)

Campaign Management (23 tools)

Ad & Creative Management (18 tools)

Keyword Management (15 tools)

Bidding & Optimization (12 tools)

Audience Management (14 tools)

Conversion Tracking (11 tools)

Advanced Reporting (25 tools)

Batch Operations (8 tools)

Extensions & Assets (12 tools)

Shopping & Performance Max (10 tools)

Local & App Campaigns (8 tools)

Automation (10 tools)

Insights & Analytics (8 tools)

Labels & Organization (7 tools)

Usage Examples

Claude Desktop Conversations

Account Overview

Campaign Analysis

Keyword Optimization

Budget Management

Search Terms Discovery

Programmatic Usage

Configuration

Configuration File (config.yaml)

Environment Variables

Feature Flags

Caching Options

Architecture

Project Structure

Manager Module Pattern

MCP Tool Registration System

Data Flow

Troubleshooting

Common Errors

"Client not initialized" Error

"Invalid customer ID" Error

"Authentication failed" Error

"Insufficient permissions" Error

Rate Limiting

1. `google_ads_initialize`

2. `google_ads_list_accounts`

3. `google_ads_campaign_performance`

4. `google_ads_keyword_performance`

5. `google_ads_search_terms`

6. `google_ads_ad_group_performance`

7. `google_ads_recommendations`

8. `google_ads_update_campaign_budget`

9. `google_ads_update_campaign_status`

10. `google_ads_custom_query`