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

   • See all your Google Ads accounts in one place
   • Get account details and basic campaign information

2. Campaign Analytics & Reporting

   • Discover which campaigns are performing best
   • Track impressions, clicks, conversions, and cost metrics
   • Analyze performance trends over time
   • Compare different time periods to spot changes
   • Visualize your data with charts and graphs created by Claude

3. Keyword & Ad Performance

   • Identify top and underperforming keywords
   • Analyze ad copy effectiveness
   • Check quality scores and competitive metrics
   • Get actionable insights on how to improve your campaigns

4. Budget & Bid Management

   • Monitor campaign budgets and spending
   • Analyze bid strategies and performance
   • Identify opportunities for optimization
   • 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:

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

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

   # 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.

3. Activate the virtual environment:

   # On Mac/Linux:
   source .venv/bin/activate
   
   # On Windows:
   .venv\Scripts\activate
   

4. Install the required dependencies:

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

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

   cp .env.example .env
   

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

   # Edit the .env file with your favorite text editor
   # For Mac:
   nano .env
   
   # For Windows:
   notepad .env
   

3. 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
   

4. 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

1. Download and install Claude Desktop if you haven't already
2. Make sure you have your Google service account credentials file saved somewhere on your computer
3. Open your computer's Terminal (Mac) or Command Prompt (Windows) and type:

# For Mac users:
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# For Windows users:
notepad %APPDATA%\Claude\claude_desktop_config.json

Add the following text (this tells Claude how to connect to Google Ads):

{
  "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_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
      }
    }
  }
}

Important: Replace all paths and values with the actual information for your account:

• The first path should point to the Python executable inside your virtual environment
• The second path should point to the google_ads_server.py file inside the folder you unzipped
• The third path should point to your Google service account credentials JSON file
• Add your Google Ads Developer Token
• Add your Google Ads Manager Account ID (if applicable)

Examples:

• Mac:
  • Python path: /Users/ernesto/Documents/mcp-google-ads/.venv/bin/python
  • Script path: /Users/ernesto/Documents/mcp-google-ads/google_ads_server.py
• Windows:
  • Python path: C:\\Users\\ernesto\\Documents\\mcp-google-ads\\.venv\\Scripts\\python.exe
  • Script path: C:\\Users\\ernesto\\Documents\\mcp-google-ads\\google_ads_server.py

4. Save the file:

   • Mac: Press Ctrl+O, then Enter, then Ctrl+X to exit
   • Windows: Click File > Save, then close Notepad

5. Restart Claude Desktop

6. When Claude opens, you should now see Google Ads tools available in the tools section

5a. Connect to Cursor (AI Code Editor)

Cursor is an AI-powered code editor that can be enhanced with MCP tools. You can integrate this Google Ads MCP tool with Cursor to analyze advertising data directly within your coding environment.

Setting Up Cursor Integration

1. If you haven't already, download and install Cursor

2. Create a Cursor MCP configuration file:

   For project-specific configuration: Create a .cursor/mcp.json file in your project directory.

   For global configuration (available in all projects): Create a ~/.cursor/mcp.json file in your home directory.

3. Add the following configuration to your MCP config file:

   {
     "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_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json",
           "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
           "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
         }
       }
     }
   }
   

   Important: Replace all paths and values with the actual information for your account, just like in the Claude Desktop configuration.

4. Restart Cursor or reload the workspace to apply the new configuration.

5. The Google Ads MCP will now appear in Cursor's "Available Tools" section and can be used by Cursor's AI agent when needed.

Using Google Ads MCP in Cursor

When working in Cursor, you can ask the AI agent to use the Google Ads tools directly. For example:

• "Use the Google Ads MCP to list all my accounts and show me which ones have the highest spend."
• "Can you analyze my campaign performance for the last 30 days using the Google Ads MCP?"
• "Run a GAQL query to find my top converting keywords using the Google Ads tools."

Cursor will prompt you to approve the tool usage (unless you've enabled Yolo mode) and then display the results directly in the chat interface.

Cursor-Specific Features

When using the Google Ads MCP with Cursor, you can:

1. Combine Code and Ads Analysis: Ask Cursor to analyze your marketing-related code alongside actual campaign performance data.
2. Generate Data Visualizations: Request charts and visualizations of your ad performance directly in your development environment.
3. Implement Recommendations: Let Cursor suggest code improvements based on your actual advertising data.

This integration is particularly valuable for developers working on marketing automation, analytics dashboards, or e-commerce applications where ad performance directly impacts code decisions.

6. Start Analyzing Your Advertising Data!

Now you can ask Claude questions about your Google Ads data! Claude can not only retrieve the data but also analyze it, explain trends, and create visualizations to help you understand your advertising performance better.

Here are some powerful prompts you can use with each tool:

Tool Name	Sample Prompt
list_accounts	"List all my Google Ads accounts and tell me which ones have the highest spend this month."
execute_gaql_query	"Execute this query for account 123-456-7890: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000"
get_campaign_performance	"Show me the top 10 campaigns for account 123-456-7890 in the last 30 days, highlight any with ROAS below 2, and suggest optimization strategies."
get_ad_performance	"Do a comprehensive analysis of which ad copy elements are driving the best CTR in my search campaigns and give me actionable recommendations."
run_gaql	"Run this query and format it as a CSV: SELECT ad_group.name, metrics.clicks, metrics.conversions FROM ad_group WHERE campaign.name LIKE '%Brand%'"

You can also ask Claude to combine multiple tools and analyze the results. For example:

• "Find my top 20 converting keywords, check their quality scores and impression share, and create a report highlighting opportunities for scaling."

• "Analyze my account's performance trend over the last 90 days, identify my fastest-growing campaigns, and check if there are any budget limitations holding them back."

• "Compare my desktop vs. mobile ad performance, visualize the differences with charts, and recommend specific campaigns that need mobile bid adjustments based on performance gaps."

• "Identify campaigns where I'm spending the most on search terms that aren't in my keyword list, then suggest which ones should be added as exact match keywords."

Claude will use the Google Ads tools to fetch the data, present it in an easy-to-understand format, create visualizations when helpful, and provide actionable insights based on the results.

---

Data Visualization Capabilities

Claude can help you visualize your Google Ads data in various ways:

• Trend Charts: See how metrics change over time
• Comparison Graphs: Compare different campaigns or ad groups
• Performance Distributions: Understand how your ads perform across devices or audiences
• Correlation Analysis: Identify relationships between spend and conversion metrics
• Heatmaps: Visualize complex datasets with color-coded representations

Simply ask Claude to "visualize" or "create a chart" when analyzing your data, and it will generate appropriate visualizations to help you understand the information better.

---

Troubleshooting

Python Command Not Found

On macOS, the default Python command is often python3 rather than python, which can cause issues with some applications including Node.js integrations.

If you encounter errors related to Python not being found, you can create an alias:

1. Create a Python alias (one-time setup):

   # For macOS users:
   sudo ln -s $(which python3) /usr/local/bin/python
   
   # If that doesn't work, try finding your Python installation:
   sudo ln -s /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 /usr/local/bin/python
   

2. Verify the alias works:

   python --version
   

This creates a symbolic link so that when applications call python, they'll actually use your python3 installation.

Claude Configuration Issues

If you're having trouble connecting:

1. Make sure all file paths in your configuration are correct and use the full path
2. Check that your service account has access to your Google Ads accounts
3. Verify that your Developer Token is valid and correctly entered
4. Restart Claude Desktop after making any changes
5. Look for error messages in Claude's response when you try to use a tool
6. Ensure your virtual environment is activated when running the server manually

Google Ads API Limitations

If you encounter issues related to API quotas or permissions:

1. Check your Google Ads API quota limits in the Google Cloud Console
2. Ensure your Developer Token has the appropriate access level
3. Verify that you've granted the proper permissions to your service account

Other Unexpected Issues

If you encounter any other unexpected issues during installation or usage:

1. Copy the exact error message you're receiving
2. Contact Ernesto Cohnen at ernesto@ixigo.com for support, including:
   • What you were trying to do
   • The exact error message
   • Your operating system
   • Any steps you've already tried

You can also consult AI assistants which can often help diagnose and resolve technical issues by suggesting specific solutions for your situation.

Remember that most issues have been encountered by others before, and there's usually a straightforward solution available.

Testing Your Setup

The repository includes test files that let you verify your Google Ads API connection is working correctly before using it with Claude or Cursor.

Testing Basic Functionality

1. Make sure your virtual environment is activated:

   # On Mac/Linux:
   source .venv/bin/activate
   
   # On Windows:
   .venv\Scripts\activate
   

2. Configure the environment variables in the test file or set them in your environment:

   • Open test_google_ads_mcp.py in a text editor
   • Find the section starting with if not os.environ.get("GOOGLE_ADS_CREDENTIALS_PATH"):
   • Update the placeholder values with your actual credentials or comment out this section if you've set them as environment variables

3. Run the test:

   python test_google_ads_mcp.py
   

4. The test will:

   • List all your Google Ads accounts
   • Use the first account ID to test campaign performance retrieval
   • Test ad performance data
   • Retrieve ad creatives
   • Run a sample GAQL query

Testing Authentication and Token Refresh

To specifically test the authentication and token refresh mechanisms:

1. Make sure your virtual environment is activated and your .env file is configured.

2. Run the token refresh test:

   python test_token_refresh.py
   

3. This test will:

   • Verify that credentials can be loaded from your configured auth type (OAuth or service account)
   • Display information about the current token status and expiry
   • Test the customer ID formatting function
   • For OAuth tokens, attempt to refresh the token and verify it worked

The token refresh test can help confirm that both OAuth and service account credentials are properly configured before using the server with Claude or Cursor.

If all tests complete successfully, your setup is working correctly and ready to use with Claude or Cursor.

---

Contributing

Found a bug or have an idea for improvement? We welcome your input! Open an issue or submit a pull request on GitHub, or contact Ernesto Cohnen directly at ernesto@ixigo.com.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

About ixigo

ixigo is India's leading travel app, helping millions of travelers find the best deals on flights, trains, buses, and hotels. For more information, visit ixigo.com.

ixigo is a technology company that builds products to help people find the best deals on flights, trains, buses, and hotels. We're a team of travel enthusiasts who are passionate about making travel more affordable and accessible to everyone.