Google Ads MCP server

Google Ads MCP Server is a FastMCP-powered solution that connects Google Ads API directly to Claude Desktop and other MCP clients. It provides seamless OAuth 2.0 authentication, automatic token refresh, GAQL querying capabilities, and keyword research tools—allowing you to interact with your Google Ads data through natural language conversations.

Prerequisites

Before setting up the MCP server, you'll need:

• Python 3.10+ installed
• A Google Cloud Platform account
• A Google Ads account with API access

Google Cloud Platform Setup

Create Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a project" → "New Project"
3. Enter project name (e.g., "Google Ads MCP")
4. Click "Create"

Enable Google Ads API

1. In your Google Cloud Console:
   • Go to "APIs & Services" → "Library"
   • Search for "Google Ads API"
   • Click on it and press "Enable"

Create OAuth 2.0 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "+ CREATE CREDENTIALS" → "OAuth 2.0 Client ID"
3. Configure consent screen (if first time):
   • Click "Configure Consent Screen"
   • Choose "External" (unless you have Google Workspace)
   • Fill required fields:
     • App name: "Google Ads MCP"
     • User support email: Your email
     • Developer contact: Your email
   • Click "Save and Continue" through all steps
4. Create OAuth Client:
   • Application type: "Desktop application"
   • Name: "Google Ads MCP Client"
   • Click "Create"
5. Download credentials:
   • Click "Download JSON" button
   • Save file as client_secret_[long-string].json in your project directory

Google Ads API Setup

Get Developer Token

1. Sign in to Google Ads
2. Go to Tools & Settings (wrench icon in top navigation)
3. Under "Setup", click "API Center"
4. Accept Terms of Service if prompted
5. Click "Apply for token"
6. Fill out application form:
   • Describe your use case (e.g., "MCP integration for campaign analysis")
   • Provide technical details about your implementation
7. Submit and wait for approval (usually 1-3 business days)

Note: You'll initially get a test token with limited functionality. After testing, you can apply for production access.

Find Your Developer Token

Once approved:

1. Return to API Center in Google Ads
2. Copy your Developer Token (format: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)

Installation & Setup

Clone and Install

# Clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Environment Configuration

Create a .env file in your project directory:

# Copy the example file
cp .env.example .env

Edit .env with your credentials:

# Required: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Required: Path to OAuth credentials JSON file (downloaded from Google Cloud)
GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

Example .env file:

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

Claude Desktop Integration

Locate Claude Configuration

Find your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add MCP Server Configuration

Edit the configuration file and add your Google Ads MCP server:

{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

Real Example:

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python",
      "args": [
        "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py"
      ]
    }
  }
}

Important:

• Use absolute paths for all file locations
• On Windows, use forward slashes / or double backslashes \\ in paths
• Replace your_developer_token_here with your actual developer token

Restart Claude Desktop

Close and restart Claude Desktop to load the new configuration.

First-Time Authentication

Trigger OAuth Flow

1. Open Claude Desktop
2. Try any Google Ads command, for example:

   "List all my Google Ads accounts"
   

Complete Authentication

1. Browser opens automatically to Google OAuth page
2. Sign in with your Google account (the one with Google Ads access)
3. Grant permissions by clicking "Allow"
4. Browser shows success page
5. Return to Claude - your command will complete automatically!

Verify Setup

After authentication, you should see:

• A google_ads_token.json file created in your project directory
• Your Google Ads accounts listed in Claude's response

Usage Examples

Basic Account Operations

"List all my Google Ads accounts"

"Show me the account details and which ones have active campaigns"

Campaign Analysis

"Show me campaign performance for account 1234567890 in the last 30 days"

"Get conversion data for all campaigns in the last week"

"Which campaigns have the highest cost per conversion?"

Keyword Research

"Generate keyword ideas for 'digital marketing' using account 1234567890"

"Find keyword opportunities for 'AI automation' with search volume data"

"Research keywords for the page https://example.com/services"

Custom GAQL Queries

"Run this GAQL query for account 1234567890:
SELECT campaign.name, metrics.clicks, metrics.cost_micros 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS"

"Get keyword performance data:
SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
FROM keyword_view 
WHERE metrics.impressions > 100"

Advanced GAQL Examples

Campaign Performance with Revenue

SELECT 
  campaign.id,
  campaign.name, 
  metrics.clicks, 
  metrics.impressions,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign 
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

Keyword Performance Analysis

SELECT 
  campaign.name,
  ad_group_criterion.keyword.text, 
  ad_group_criterion.keyword.match_type,
  metrics.ctr,
  metrics.average_cpc,
  metrics.quality_score
FROM keyword_view 
WHERE segments.date DURING LAST_7_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions DESC

Device Performance Breakdown

SELECT 
  campaign.name,
  segments.device,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'

Troubleshooting

Authentication Issues

Issue	Solution
No tokens found	Normal for first-time setup - complete browser authentication
Token refresh failed	Delete google_ads_token.json and re-authenticate
OAuth flow failed	Check credentials file path and internet connection
Permission denied	Ensure Google account has Google Ads access

Configuration Issues

Issue	Solution
Environment variables missing	Check .env file and Claude config env section
File not found	Verify absolute paths in configuration
Module import errors	Run pip install -r requirements.txt
Python path issues	Use absolute path to Python executable

Claude Desktop Issues

Issue	Solution
Server not connecting	Restart Claude Desktop, check config file syntax
Invalid JSON config	Validate JSON syntax in config file
Permission errors	Check file permissions and paths

API Issues

Issue	Solution
Invalid customer ID	Use 10-digit format without dashes: 1234567890
API quota exceeded	Wait for quota reset or request increase
Invalid developer token	Verify token in Google Ads API Center
GAQL syntax errors	Check GAQL syntax and field names

Advanced Configuration

HTTP Transport Mode

For web deployment or remote access:

# Start server in HTTP mode
python3 server.py --http

Claude Desktop config for HTTP:

{
  "mcpServers": {
    "google-ads": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Manager Account Configuration

For managing multiple accounts under an MCC:

# Add to .env file
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "google-ads" '{"command":"/full/path/to/your/project/.venv/bin/python","args":["/full/path/to/your/project/server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "google-ads": {
            "command": "/full/path/to/your/project/.venv/bin/python",
            "args": [
                "/full/path/to/your/project/server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "google-ads": {
            "command": "/full/path/to/your/project/.venv/bin/python",
            "args": [
                "/full/path/to/your/project/server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect