Google Ads MCP

A tool that connects Google Ads with Claude AI, allowing you to analyze your advertising data through natural language conversations. This integration gives you access to campaign information, performance metrics, keyword analytics, and ad management—all through simple chat with Claude.

---

What Can This Tool Do For Advertising Professionals?

1. Account Management
2. See all your Google Ads accounts in one place

3. Get account details and basic campaign information

4. Campaign Analytics & Reporting

5. Discover which campaigns are performing best
6. Track impressions, clicks, conversions, and cost metrics
7. Analyze performance trends over time
8. Compare different time periods to spot changes

9. Visualize your data with charts and graphs created by Claude

10. Keyword & Ad Performance

11. Identify top and underperforming keywords
12. Analyze ad copy effectiveness
13. Check quality scores and competitive metrics

14. Get actionable insights on how to improve your campaigns

15. Budget & Bid Management

16. Monitor campaign budgets and spending
17. Analyze bid strategies and performance
18. Identify opportunities for optimization
19. Get recommendations for budget allocation

---

Google Ads MCP Architecture Flow

flowchart TB
    User(User) -->|Interacts with| Claude
    Claude(Claude AI Assistant) -->|Makes requests to| MCP[Google Ads MCP Server]
    User -->|Can also use| Cursor[Cursor AI Code Editor]
    Cursor -->|Makes requests to| MCP

    subgraph "MCP Server"
        FastMCP[FastMCP Server] 
        Tools[Available Tools]
        Auth[Authentication]

        FastMCP -->|Exposes| Tools
        FastMCP -->|Uses| Auth
    end

    subgraph "Google Ads Tools"
        ListAccounts[list_accounts]
        ExecuteGAQL[execute_gaql_query]
        CampaignPerf[get_campaign_performance]
        AdPerf[get_ad_performance]
        RunGAQL[run_gaql]
    end

    Tools -->|Includes| ListAccounts
    Tools -->|Includes| ExecuteGAQL
    Tools -->|Includes| CampaignPerf
    Tools -->|Includes| AdPerf
    Tools -->|Includes| RunGAQL

    subgraph "Authentication"
        OAuth[OAuth 2.0 Client ID]
        ServiceAccount[Service Account]
        Credentials[Google Ads API Credentials]

        OAuth -->|Provides| Credentials
        ServiceAccount -->|Provides| Credentials
    end

    MCP -->|Communicates with| GoogleAdsAPI[Google Ads API]
    GoogleAdsAPI -->|Returns| AdData[Advertising Data]
    AdData -->|Analyzed by| Claude
    AdData -->|Visualized by| Claude
    AdData -->|Can be used by| Cursor

    Credentials -->|Authorizes| GoogleAdsAPI

    subgraph "Configuration"
        EnvVars[Environment Variables]
        ConfigFiles[Configuration Files]

        EnvVars -->|Configures| MCP
        ConfigFiles -->|Configures| Claude
        ConfigFiles -->|Configures| Cursor
    end

Available Tools

Here's what you can ask Claude to do once you've set up this integration:

What You Can Ask For	What It Does	What You'll Need to Provide
list_accounts	Shows all your Google Ads accounts	Nothing - just ask!
execute_gaql_query	Runs a Google Ads Query Language query	Your account ID and a GAQL query
get_campaign_performance	Shows campaign metrics with performance data	Your account ID and time period
get_ad_performance	Detailed analysis of your ad creative performance	Your account ID and time period
run_gaql	Runs any arbitrary GAQL query with formatting options	Your account ID, query, and format (table, JSON, or CSV)

Using the Advanced Query Tools

The run_gaql tool is especially powerful as it allows you to run any custom Google Ads Query Language (GAQL) query. Here are some example queries you can use:

Example 1: Basic campaign metrics

SELECT 
    campaign.name, 
    metrics.clicks, 
    metrics.impressions 
FROM campaign 
WHERE segments.date DURING LAST_7DAYS

Example 2: Ad group performance

SELECT 
    ad_group.name, 
    metrics.conversions, 
    metrics.cost_micros 
FROM ad_group 
WHERE metrics.clicks > 100

Example 3: Keyword analysis

SELECT 
    keyword.text, 
    metrics.average_position, 
    metrics.ctr 
FROM keyword_view 
ORDER BY metrics.impressions DESC

For a complete list of all available tools and their detailed descriptions, ask Claude to "list tools" after setup.

---

Getting Started (No Coding Experience Required!)

1. Set Up Google Ads API Access

Before using this tool, you'll need to create API credentials that allow Claude to access your Google Ads data. You can choose between two authentication methods:

Option A: OAuth 2.0 Client ID (User Authentication)

Best for individual users or desktop applications:

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Ads API
4. Go to "Credentials" → "Create Credentials" → "OAuth Client ID"
5. Choose "Desktop Application" as the application type
6. Download the OAuth client configuration file (client_secret.json)
7. Create a Google Ads API Developer token (see below)

Option B: Service Account (Server-to-Server Authentication)

Better for automated systems or managing multiple accounts:

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Ads API
4. Go to "Credentials" → "Create Credentials" → "Service Account"
5. Download the service account key file (JSON)
6. Grant the service account access to your Google Ads accounts
7. Create a Google Ads API Developer token (see below)

Authentication Token Refreshing

The application now includes robust token refresh handling:

• OAuth 2.0 Tokens: The tool will automatically refresh expired OAuth tokens when possible, or prompt for re-authentication if the refresh token is invalid.
• Service Account Tokens: Service account tokens are automatically generated and refreshed as needed without user intervention.

Authentication Method Comparison

Choose OAuth 2.0 Client ID if:

• You're building a desktop application
• Users need to explicitly grant access
• You're managing a single account or a few personal accounts
• You want users to have control over access permissions

Choose Service Account if:

• You're building an automated system
• You need server-to-server authentication
• You're managing multiple accounts programmatically
• You don't want/need user interaction for authentication
• You need automatic token refreshing without user intervention

Getting a Developer Token

1. Sign in to your Google Ads account at https://ads.google.com
2. Click on Tools & Settings (wrench icon) in the top navigation
3. Under "Setup", click "API Center"
4. If you haven't already, accept the Terms of Service
5. Click "Apply for token"
6. Fill out the application form with details about how you plan to use the API
7. Submit the application and wait for approval (usually 1-3 business days)

Note: Initially, you'll get a test Developer Token that has some limitations. Once you've tested your implementation, you can apply for a production token that removes these restrictions.

Understanding the Login Customer ID

The GOOGLE_ADS_LOGIN_CUSTOMER_ID is optional and is primarily used when:

• You're working with a Google Ads Manager Account (MCC)
• You need to access multiple client accounts under that manager account

The Login Customer ID should be your Manager Account ID (format: XXX-XXX-XXXX) if:

• You're accessing multiple accounts under a manager account
• You want to use manager account credentials to access client accounts

You can skip this setting if:

• You're only accessing a single Google Ads account
• You're using credentials directly from the account you want to access

To find your Manager Account ID:

1. Sign in to your Google Ads Manager Account
2. Click on the settings icon (gear)
3. Your Manager Account ID will be displayed in the format XXX-XXX-XXXX
4. Download the credentials file (a JSON file)

🎬 Watch this beginner-friendly tutorial on Youtube: COMING SOON

2. Install Required Software

You'll need to install these tools on your computer:

• Python (version 3.11 or newer) - This runs the connection between Google Ads and Claude
• Node.js - Required for running the MCP inspector and certain MCP components
• Claude Desktop - The AI assistant you'll chat with

Make sure both Python and Node.js are properly installed and available in your system path before proceeding.

3. Download the Google Ads MCP

You need to download this tool to your computer. The easiest way is:

1. Click the green "Code" button at the top of this page
2. Select "Download ZIP"
3. Unzip the downloaded file to a location you can easily find (like your Documents folder)

Alternatively, if you're familiar with Git:

git clone https://github.com/ixigo/mcp-google-ads.git

4. Install Required Components

Open your computer's Terminal (Mac) or Command Prompt (Windows):

1. Navigate to the folder where you unzipped the files:

bash # Example (replace with your actual path): cd ~/Documents/mcp-google-ads-main

1. Create a virtual environment (this keeps the project dependencies isolated):

```bash # Using uv (recommended): uv venv .venv

# If uv is not installed, install it first: pip install uv # Then create the virtual environment: uv venv .venv

# OR using standard Python: python -m venv .venv ```

Note: If you get a "pip not found" error when trying to install uv, see the "If you get 'pip not found' error" section below.

1. Activate the virtual environment:

```bash # On Mac/Linux: source .venv/bin/activate

# On Windows: .venv\Scripts\activate ```

1. Install the required dependencies:

```bash # Using uv: uv pip install -r requirements.txt

# OR using standard pip: pip install -r requirements.txt

# If you encounter any issues with the MCP package, install it separately: pip install mcp ```

If you get "pip not found" error:

```bash # First ensure pip is installed and updated: python3 -m ensurepip --upgrade python3 -m pip install --upgrade pip

# Then try installing the requirements again: python3 -m pip install -r requirements.txt

# Or to install uv: python3 -m pip install uv ```

When you see (.venv) at the beginning of your command prompt, it means the virtual environment is active and the dependencies will be installed there without affecting your system Python installation.

5. Setting Up Environment Configuration

The Google Ads MCP now supports environment file configuration for easier setup.

Using .env File (Recommended)

1. Copy the .env.example file to .env in your project directory:

bash cp .env.example .env

1. Edit the .env file with your actual configuration values:

```bash # Edit the .env file with your favorite text editor # For Mac: nano .env

# For Windows: notepad .env ```

1. Set the following values in your .env file:

``` # Authentication Type: "oauth" or "service_account" GOOGLE_ADS_AUTH_TYPE=oauth

# Path to your credentials file (OAuth client secret or service account key) GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json

# Your Google Ads Developer Token GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Optional: Manager Account ID (if applicable) GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id ```

1. Save the file.

The application will automatically load these values from the .env file when it starts.

Using Direct Environment Variables

You can also set environment variables directly in your system or in the configuration files for Claude or Cursor:

For Claude Desktop

{
  "mcpServers": {
    "googleAdsServer": {
      "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python",
      "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"],
      "env": {
        "GOOGLE_ADS_AUTH_TYPE": "oauth",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
      }
    }
  }
}

For Cursor

{
  "mcpServers": {
    "googleAdsServer": {
      "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python",
      "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"],
      "env": {
        "GOOGLE_ADS_AUTH_TYPE": "oauth",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
      }
    }
  }
}

6. Connect Claude to Google Ads