The Google Ads MCP is a tool that connects Google Ads with Claude AI, allowing you to analyze advertising data through natural language conversations. It provides access to campaign information, performance metrics, keyword analytics, and ad management through simple chat interactions.
Before using this tool, you need to create API credentials:
Download the tool:
git clone https://github.com/ixigo/mcp-google-ads.git
Or download the ZIP file from the GitHub repository.
Navigate to the folder:
cd mcp-google-ads-main
Create and activate a virtual environment:
# Using uv (recommended):
pip install uv
uv venv .venv
# OR using standard Python:
python -m venv .venv
# Activate on Mac/Linux:
source .venv/bin/activate
# Activate on Windows:
.venv\Scripts\activate
Install dependencies:
# Using uv:
uv pip install -r requirements.txt
# OR using standard pip:
pip install -r requirements.txt
Create an environment file:
cp .env.example .env
Edit the .env file with your actual configuration values:
# Authentication Type: "oauth" or "service_account"
GOOGLE_ADS_AUTH_TYPE=oauth
# Path to your credentials file
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
Edit the Claude configuration file:
# 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 configuration:
{
"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"
}
}
}
}
Save the file and restart Claude Desktop
The Google Ads MCP provides several tools that you can use by asking Claude:
| Tool Name | What It Does | What You 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 | Your account ID and time period |
get_ad_performance |
Analyzes ad creative performance | Your account ID and time period |
run_gaql |
Runs any arbitrary GAQL query | Your account ID, query, and format (table, JSON, or CSV) |
Basic campaign metrics:
SELECT
campaign.name,
metrics.clicks,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
Ad group performance:
SELECT
ad_group.name,
metrics.conversions,
metrics.cost_micros
FROM ad_group
WHERE metrics.clicks > 100
Keyword analysis:
SELECT
keyword.text,
metrics.average_position,
metrics.ctr
FROM keyword_view
ORDER BY metrics.impressions DESC
On macOS, create a Python alias:
sudo ln -s $(which python3) /usr/local/bin/python
Test your Google Ads API connection:
# Make sure your virtual environment is activated
python test_google_ads_mcp.py
Test authentication and token refresh:
python test_token_refresh.py
If you encounter issues:
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.
To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"cursor-rules-mcp": {
"command": "npx",
"args": [
"-y",
"cursor-rules-mcp"
]
}
}
}
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.
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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.