Google Ads MCP Server - Setup Guide

A comprehensive Model Context Protocol server for Google Ads API integration, providing powerful tools for campaign analysis, optimization, and management.

Features

Analysis Tools

• List Accounts - View all accessible Google Ads accounts
• Campaign Performance - Comprehensive metrics with filtering and date ranges
• Keyword Performance - Quality scores, positions, and conversion data
• Search Terms Report - Discover actual queries triggering your ads
• Ad Group Performance - Group-level metrics and analysis
• Recommendations - Google's AI-powered optimization suggestions

Management Tools

• Update Campaign Budget - Adjust daily budget allocations
• Pause/Enable Campaigns - Control campaign status
• Custom GAQL Queries - Execute advanced custom queries

Prerequisites

1. Google Ads API Access

You need:

• Developer Token - Apply at https://developers.google.com/google-ads/api/docs/get-started/dev-token
• Google Ads Account - Active account with campaigns
• OAuth2 Credentials - Client ID and Client Secret

2. OAuth2 Setup

Step 1: Create OAuth2 Credentials

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Google Ads API
4. Go to "Credentials" "Create Credentials" "OAuth client ID"
5. Choose "Desktop app" as application type
6. Save your Client ID and Client Secret

Step 2: Generate Refresh Token

You need to generate a refresh token using the OAuth2 flow. Here's a Python script to help:

from google_auth_oauthlib.flow import InstalledAppFlow

# Your OAuth2 credentials
CLIENT_ID = 'your-client-id.apps.googleusercontent.com'
CLIENT_SECRET = 'your-client-secret'

# Google Ads API scope
SCOPES = ['https://www.googleapis.com/auth/adwords']

# Run OAuth flow
flow = InstalledAppFlow.from_client_config(
    {
        "installed": {
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    },
    scopes=SCOPES
)

credentials = flow.run_local_server(port=0)
print(f"Refresh Token: {credentials.refresh_token}")

Save this as generate_token.py and run it. It will open a browser for authorization and print your refresh token.

Install required package first:

pip install google-auth-oauthlib

Installation

Step 1: Install Dependencies

pip install -r requirements.txt

Or install manually:

pip install google-ads mcp httpx pydantic

Step 2: Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["/absolute/path/to/google_ads_mcp.py"],
      "env": {}
    }
  }
}

Replace /absolute/path/to/google_ads_mcp.py with the actual path to the server file.

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop for the changes to take effect.

Usage

Initial Setup

When you first interact with Claude Desktop after installing the MCP server, initialize the connection with your credentials:

Initialize my Google Ads connection with these credentials:
- Developer Token: INSERT_YOUR_DEV_TOKEN
- Client ID: INSERT_YOUR_CLIENT_ID.apps.googleusercontent.com
- Client Secret: INSERT_YOUR_CLIENT_SECRET
- Refresh Token: INSERT_YOUR_REFRESH_TOKEN
- Login Customer ID: INSERT_YOUR_MCC_ID (optional, only if using MCC)

Claude will call the google_ads_initialize tool and confirm the connection.

Example Queries

Once initialized, you can ask Claude things like:

Account Overview

"Show me all my Google Ads accounts"
"List all accessible accounts"

Campaign Analysis

"Show campaign performance for the last 30 days for account 1234567890"
"Which campaigns spent the most in the last week?"
"Show me only enabled campaigns with at least $100 in spend"

Keyword Optimization

"Analyze keyword performance for campaign 12345"
"Show me keywords with quality score below 5"
"Which keywords have the highest cost per conversion?"

Search Terms Discovery

"Get search terms report for the last 30 days"
"What search queries are triggering my ads?"
"Find search terms with high impressions but low CTR"

Budget Management

"Increase budget for campaign 12345 to $100 per day"
"Pause campaign 67890"
"Enable campaign 54321"

Advanced Analysis

"Show me Google's optimization recommendations"
"Compare ad group performance across all campaigns"
"Find keywords with average position worse than 3"

Custom Queries

"Execute this GAQL query: SELECT campaign.name, metrics.clicks FROM campaign"

Available Tools

1. google_ads_initialize

Initialize API connection with OAuth credentials.

Parameters:

• developer_token (required)
• client_id (required)
• client_secret (required)
• refresh_token (required)
• login_customer_id (optional) - MCC account ID

2. google_ads_list_accounts

List all accessible Google Ads accounts.

Parameters:

• response_format - "markdown" or "json"

3. google_ads_campaign_performance

Get comprehensive campaign metrics.

Parameters:

• customer_id (required) - Account ID without hyphens
• date_range - TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, etc.
• campaign_status - Filter by ENABLED, PAUSED, or REMOVED
• min_cost - Minimum cost threshold
• limit - Max results (default: 50)
• response_format - "markdown" or "json"

4. google_ads_keyword_performance

Analyze keyword-level performance.

Parameters:

• customer_id (required)
• campaign_id (…