Google Ads MCP Server

How to use

Operate the Google Ads MCP Server by wiring Claude and your code editor or Cursor to the local MCP endpoint. You will be able to list accounts, fetch campaign and ad performance, run custom GAQL queries, and visualize trends. Use natural language prompts in Claude to trigger these tools, and combine results from multiple tools to build comprehensive reports.

How to install

Prerequisites: you need Python installed (3.11 or newer) and Node.js for optional MCP inspector components. You will also use uv (or standard Python virtualenv) to create an isolated environment.

# 1) Prepare a working directory
mkdir -p ~/mcp-google-ads
cd ~/mcp-google-ads

# 2) Create a virtual environment (recommended with uv)
uv venv .venv

# If uv is not installed, install it and then create the venv
pip install uv
uv venv .venv

# 3) Activate the virtual environment
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# 4) Install dependencies
uv pip install -r requirements.txt
# or with standard pip
pip install -r requirements.txt

# 5) Ensure the MCP package is available
pip install mcp

Additional sections

Configuration and runtime details are provided below. You will run the local Python server and connect Claude Desktop or Cursor with the appropriate environment variables.

Configure environment variables in a .env file or via explicit environment settings in Claude or Cursor. The following variables are required by the MCP server:

# Example .env content
GOOGLE_ADS_AUTH_TYPE=oauth
GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id_here

MCP server configuration example

The server is exposed locally as a stdio-based MCP endpoint. Use the following configuration in Claude Desktop or Cursor to start and connect the Google Ads MCP server.

{
  "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"
      }
    }
  }
}

Connecting Claude Desktop and Cursor

To connect Claude Desktop or Cursor to the Google Ads MCP, place the same command and environment details in the MCP section of their configuration. After saving, restart the application to load the new MCP server connection.

Once connected, you will see Google Ads tools available in the tools section and can start querying your data with prompts like asking for account lists, campaign performance, or keyword analytics.

Tools and usage patterns

You can list accounts, fetch campaign performance, analyze ad performance, and run GAQL queries. Combine results from multiple tools to create comprehensive reports and visualizations.

Troubleshooting

If you encounter issues, verify that the paths in the environment configuration are correct and that the service account credentials have access to your Google Ads accounts. Ensure the Developer Token is valid and that Claude Desktop or Cursor has been restarted after changes. Check for error messages in the tool responses to guide fixes.

Notes

Token refreshing for OAuth and service accounts is supported. OAuth tokens refresh automatically when possible, while service account tokens are managed without user intervention. Ensure your credentials and IDs are kept secure and that access is limited to authorized users.

list_accounts

Shows all Google Ads accounts available to the authenticated user.

execute_gaql_query

Runs a Google Ads Query Language (GAQL) query for a specific account.

get_campaign_performance

Returns campaign-level performance metrics for a chosen time period.

get_ad_performance

Provides detailed insights into ad performance and creative effectiveness.

run_gaql

Executes an arbitrary GAQL query with options to format the output (table, JSON, CSV).