Google Ads API v20 MCP Server

A comprehensive Model Context Protocol (MCP) server that provides full access to Google Ads API v20 functionality. This server enables AI assistants to perform any Google Ads operation through natural language commands.

Features

Complete API Coverage

• Account Management: List accounts, get account info, view hierarchy
• Campaign Management: Create, update, pause/resume campaigns with all v20 features
• Ad Group Management: Full CRUD operations for ad groups
• Ad Creation: Responsive search ads, expanded text ads, and more
• Asset Management: Upload and manage images, text assets
• Budget Management: Create and manage shared budgets
• Keyword Management: Add keywords, negative keywords (including Performance Max campaign-level negatives)
• Reporting & Analytics: Custom GAQL queries, performance reports, search terms
• Advanced Features: Recommendations, change history, experiments

Intelligent Features

• Automatic Retry Logic: Handles transient errors with exponential backoff
• Error Documentation: Links to official Google Ads API error documentation
• Partial Failure Handling: Continues processing when some operations fail
• Token Auto-Refresh: Automatically refreshes OAuth tokens
• Self-Rewriting: Can look up documentation and retry failed operations

Installation

# Install with pip
pip install -e .

# Or install dependencies directly
pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

Configuration

Environment Variables

Create a .env file or set these environment variables:

# OAuth2 Authentication
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_client_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token

# OR Service Account Authentication
GOOGLE_ADS_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
[email protected]  # Optional

# Required for all auth methods
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890  # Manager account ID if applicable

Configuration File

Alternatively, create a config file at ~/.config/google-ads-mcp/config.json:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "refresh_token": "your_refresh_token",
  "developer_token": "your_developer_token",
  "login_customer_id": "1234567890"
}

MCP Configuration

Add to your Claude Desktop config (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_token",
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Usage Examples

Basic Operations

# List all accounts