Google Ads MCP Server

Model Context Protocol (MCP) server for Google Ads API integration. Provides comprehensive tools for managing Google Ads campaigns, ad groups, ads, keywords, assets, and performance insights.

Features

Account Management

• google_ads_list_accounts - List all accessible accounts
• google_ads_get_account_info - Get detailed account information

Campaign Operations

• google_ads_list_campaigns - List campaigns with filtering and pagination
• google_ads_get_campaign - Get detailed campaign settings
• google_ads_get_campaign_insights - Get performance metrics
• google_ads_create_campaign - Create new campaigns
• google_ads_update_campaign_status - Enable/pause/remove campaigns
• google_ads_set_campaign_schedule - Set ad scheduling (day parting)
• google_ads_update_campaign_budget - Update daily budget

Ad Groups

• google_ads_list_ad_groups - List ad groups for a campaign
• google_ads_create_ad_group - Create new ad groups
• google_ads_update_ad_group_status - Enable/pause/remove ad groups

Ads

• google_ads_list_ads - List ads for an ad group
• google_ads_create_responsive_search_ad - Create RSA ads
• google_ads_update_ad_status - Enable/pause/remove ads

Keywords

• google_ads_list_keywords - List keywords for an ad group
• google_ads_add_keywords - Add keywords with match types
• google_ads_remove_keywords - Remove keywords

Negative Keywords

• google_ads_list_negative_keywords - List negative keywords
• google_ads_add_negative_keywords - Add negative keywords (campaign/ad group level)
• google_ads_remove_negative_keywords - Remove negative keywords

Performance Max Campaigns

• google_ads_create_pmax_campaign - NEW Create complete PMAX campaigns with text and image assets
• google_ads_get_asset_performance - Get PMax asset performance metrics
• google_ads_create_text_assets - Create and add text assets to asset groups
• google_ads_remove_asset_from_group - Remove assets from asset groups
• google_ads_update_asset_group_assets - Batch update assets (add + remove)

Search Terms & Insights

• google_ads_get_search_terms - Get search terms report
• google_ads_get_budget_utilization - Check budget spend vs allocation

Quality & Optimization

• google_ads_get_keyword_quality_scores - Get Quality Score breakdown
• google_ads_get_ad_strength - Get RSA Ad Strength ratings
• google_ads_get_policy_issues - Find disapproved ads/assets

Recommendations

• google_ads_list_recommendations - List Google's optimization recommendations
• google_ads_apply_recommendation - Apply a recommendation
• google_ads_dismiss_recommendation - Dismiss a recommendation

Conversion Tracking

• google_ads_list_conversion_actions - List configured conversion actions
• google_ads_get_conversion_stats - Get conversion statistics by campaign
• google_ads_get_conversions_by_action - NEW Get conversions breakdown by conversion action name
• google_ads_get_campaign_conversion_goals - Get campaign conversion goals configuration

Geographic Targeting

• google_ads_get_geo_targets - Get campaign geo targeting settings
• google_ads_search_geo_targets - Search for locations to target
• google_ads_set_geo_targets - Add geo targeting (include/exclude)
• google_ads_remove_geo_targets - Remove geo targeting
• google_ads_get_geo_performance - Get performance by geographic location

Installation

Prerequisites

• Python 3.9 or later
• Google Ads API access (developer token, OAuth2 credentials)
• Active Google Ads account

Setup

1. Clone or download this repository

2. Create virtual environment and install dependencies:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   

3. Configure Google Ads API credentials:

   Create a .env file based on .env.example:

   cp .env.example .env
   

   Edit .env and add your credentials:

   GOOGLE_ADS_DEVELOPER_TOKEN=your_token
   GOOGLE_ADS_CLIENT_ID=your_client_id.apps.googleusercontent.com
   GOOGLE_ADS_CLIENT_SECRET=your_secret
   GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token
   GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_mcc_id  # Optional, for MCC accounts
   

Getting Google Ads API Credentials

1. Developer Token:

   • Go to Google Ads API Center
   • Apply for API access and get your developer token

2. OAuth2 Credentials:

   • Create a project in Google Cloud Console
   • Enable Google Ads API
   • Create OAuth 2.0 credentials (Desktop app)
   • Download client ID and secret

3. Refresh Token:

   • Use the Google Ads API authentication guide
   • Run OAuth flow to generate refresh token

Usage

Running the Server

source .venv/bin/activate
python google_ads_mcp.py

Adding to Claude Desktop

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "google-ads": {
      "command": "/path/to/mcp-google-ads/.venv/bin/python",
      "args": ["/path/to/mcp-google-ads/google_ads_mcp.py"],
      "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",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your_mcc_id"
      }
    }
  }
}

Adding to Claude Code

claude mcp add google-ads \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your_token \
  -e GOOGLE_ADS_CLIENT_ID=your_client_id \
  -e GOOGLE_ADS_CLIENT_SECRET=your_secret \
  -e GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token \
  -e GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_mcc_id \
  -- /path/to/mcp-google-ads/.venv/bin/python /path/to/mcp-google-ads/google_ads_mcp.py

Tool Documentation

Performance Max Campaign Creation

google_ads_create_pmax_campaign

Create a complete Performance Max campaign with all required assets in a single operation.

Parameters:

• customer_id (required): 10-digit account ID
• campaign_name (required): Campaign name
• daily_budget_micros (required): Daily budget in micros (1000000 = $1)
• final_urls (required): Landing page URLs (1-10)
• headlines (required): Headlines (3-15, max 30 chars each)
• long_headlines (required): Long headlines (1-5, max 90 chars each)
• descriptions (required): Descriptions (2-5, max 90 chars each)
• business_name (required): Business name (max 25 chars)
• marketing_images (required): Local file paths for landscape images (1.91:1 ratio)
• square_marketing_images (required): Local file paths for square images (1:1 ratio)
• logo_images (required): Local file paths for logo images (1:1 ratio)
• portrait_marketing_images (optional): Local file paths for portrait images (4:5 ratio)
• geo_target_country_codes (required): Country codes for targeting (e.g., ["IT", "US"])
• bidding_strategy (optional): MAXIMIZE_CONVERSIONS or MAXIMIZE_CONVERSION_VALUE
• start_paused (optional): Create paused for review (default: true)

Example:

Create a PMAX campaign "Summer Sale" with $50/day budget targeting Italy

Features:

• Creates budget, campaign, asset group, and all assets atomically
• Uploads images from local file paths
• Supports all PMAX asset types (text + images)
• Automatic geo targeting configuration
• Created in PAUSED status for safety review

Conversion Tools

google_ads_get_conversions_by_action

Get conversions breakdown by conversion action name. Shows which conversion types are performing best.

Parameters:

• customer_id (required): 10-digit account ID
• campaign_id (optional): Filter by campaign
• date_range (optional): TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc. (default: LAST_30_DAYS)
• min_conversions (optional): Minimum conversions threshold (default: 0)
• limit (optional): Max results (1-200, default: 50)
• response_format (optional): "markdown" or "json"

Example:

Show me conversions breakdown by action for account 1234567890
Which conversion actions have the highest value?

Note: Cost/CPA metrics are not available per conversion action due to Google Ads API limitations. Use google_ads_get_conversion_stats for cost metrics at campaign level.

Response Formats

Markdown Format (Default)

Human-readable format with:

• Headers and sections
• Bullet points
• Tables for metrics
• Clear hierarchy
• Formatted dates and currency

JSON Format

Machine-readable format with:

• Complete structured data
• All available fields
• Nested objects
• Pagination metadata

Error Handling

The server provides clear, actionable error messages for:

• Authentication errors (invalid credentials)
• Authorization errors (no access to account)
• Rate limiting (API quota exceeded)
• Invalid customer IDs
• Resource not found
• Budget configuration issues
• Field validation errors

Best Practices

1. Start Paused: New campaigns/ad groups are created in PAUSED status - review settings before enabling
2. Test Accounts: Use test accounts for development
3. Monitor Budgets: Set appropriate budget limits
4. Use Filters: Apply status filters and pagination for large accounts
5. Check Permissions: Ensure proper access to customer accounts

Troubleshooting

Authentication Errors

• Verify developer token is valid
• Check OAuth credentials are current
• Regenerate refresh token if expired

Permission Errors

• Confirm you have access to the customer account
• For MCC accounts, set GOOGLE_ADS_LOGIN_CUSTOMER_ID

Rate Limiting

• Implement delays between requests
• Use batch operations when available
• Monitor API quota in Google Ads API Center

Development

Testing

# Syntax check
python -m py_compile google_ads_mcp.py

# Run server
python google_ads_mcp.py

Support

• Google Ads API Documentation
• Google Ads Python Client
• MCP Documentation

License

MIT License - See LICENSE file for details

Version History

v1.4.0 (Current)

• Added google_ads_create_pmax_campaign - Create complete PMAX campaigns with text and image assets
• PMAX campaigns now support local image file uploads (marketing, square, logo, portrait)
• Atomic batch operations using GoogleAdsService.Mutate with temporary IDs
• All PMAX asset management tools tested and verified

v1.3.0

• Added google_ads_get_conversions_by_action - Conversion breakdown by action name
• Full conversion tracking tools
• Geographic targeting and performance
• Performance Max asset management
• Quality scores and ad strength
• Recommendations management
• Budget utilization tracking

v1.0.0 (Initial)

• Account management tools
• Campaign CRUD operations
• Ad groups, ads, keywords
• Performance insights