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
GOOGLE_ADS_IMPERSONATED_EMAIL=user@example.com  # 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
Use the list_accounts tool

# Create a campaign
Use create_campaign with customer_id="1234567890", name="Summer Sale 2025", 
budget_amount=100.0, campaign_type="SEARCH"

# Get campaign performance
Use get_campaign_performance with customer_id="1234567890", date_range="LAST_30_DAYS"

Advanced Queries

# Run custom GAQL query
Use run_gaql_query with query:
SELECT campaign.name, metrics.clicks, metrics.conversions
FROM campaign
WHERE metrics.impressions > 1000
  AND segments.date DURING LAST_7_DAYS
ORDER BY metrics.clicks DESC

Performance Max Features (v20)

# Add negative keywords to Performance Max campaign
Use add_negative_keywords with customer_id="1234567890", 
campaign_id="123", keywords=["cheap", "discount", "free"]

Error Handling

The server provides detailed error information:

• Error type and code
• Human-readable message
• Whether the error is retryable
• Link to official documentation
• Suggestions for fixing common errors

Development

Running Tests

pytest tests/

Adding New Tools

1. Add tool definition to `_register_tools()` in `tools.py`

2. Implement the handler method

3. Update documentation

Debugging

# Run with debug logging
export LOG_LEVEL=DEBUG
python -m google-ads-mcp

Security Notes

• Never commit credentials to version control
• Use service accounts for production environments
• Enable 2FA on Google Ads accounts
• Regularly rotate refresh tokens
• Monitor API usage and set alerts

API Version Support

This server is built for Google Ads API v20 (released June 2025) and includes:

• Campaign-level negative keywords for Performance Max
• Enhanced Demand Gen reporting with channel segmentation
• Platform comparable conversions
• All v20-specific features and improvements

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Submit a pull request

Support

For issues and questions:

• Check the Google Ads API documentation
• Review error messages and documentation links
• Open an issue on GitHub