Google Ads API v20

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.

- 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

- 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

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

Create a.envfile 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

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

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

# 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"

# 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

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

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
- Add tool definition to_register_tools()intools.py
- Implement the handler method
- Update documentation

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

- 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

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

MIT License - See LICENSE file for details
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request

- Check theGoogle Ads API documentation
- Review error messages and documentation links
- Open an issue on GitHub

Cross-platform ad campaign management for AI agents across Google, Meta, LinkedIn, Reddit, TikTok, and more. 140+ tools with read/write access.