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