mcp-google-ads

mikdeangelis/mcp-google-ads

3.2

If you are the rightful owner of mcp-google-ads and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Google Ads MCP Server is a Model Context Protocol server designed for seamless integration with the Google Ads API, offering tools for managing campaigns, ad groups, ads, keywords, and performance insights.

Tools
7
Resources
0
Prompts
0

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 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:

  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:

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

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

License

MIT License - See LICENSE file for details

Version History

v1.3.0 (Current)

  • 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