# Google Ads MCP
A tool that connects [Google Ads](https://ads.google.com/) 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
```mermaid
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:
### **Read/Analysis Tools**
| **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) |
| `get_ad_creatives` | Retrieves ad copy, headlines, and descriptions | Your account ID |
| `get_account_currency` | Shows the account's default currency | Your account ID |
| `get_image_assets` | Lists image assets with download URLs | Your account ID |
| `download_image_asset` | Downloads specific image assets | Your account ID and asset ID |
| `get_asset_usage` | Shows where assets are used in campaigns | Your account ID and optional asset ID |
| `analyze_image_assets` | Performance analysis of image assets | Your account ID and time period |
### **Write/Management Tools** ✨ NEW!
| **What You Can Ask For** | **What It Does** | **What You'll Need to Provide** |
|---------------------------------|-------------------------------------------------------------|----------------------------------------------------------------|
| `create_campaign_budget` | Creates a new campaign budget | Account ID, budget name, daily amount |
| `create_campaign` | Creates a new Google Ads campaign | Account ID, campaign name, budget resource name |
| `update_campaign_status` | Enable, pause, or remove campaigns | Account ID, campaign resource name, new status |
| `update_campaign_budget` | Change which budget a campaign uses | Account ID, campaign resource name, new budget resource name |
| `create_ad_group` | Creates a new ad group within a campaign | Account ID, ad group name, campaign resource name, CPC bid |
| `add_keywords` | Adds keywords to an ad group | Account ID, ad group resource name, keyword list with bids |
| `update_keyword_status` | Enable, pause, or remove keywords | Account ID, keyword resource names, new status |
| `create_responsive_search_ad` | Creates responsive search ads with headlines/descriptions | Account ID, ad group resource name, headlines, descriptions, URLs |
| `add_negative_keywords` | Adds negative keywords to campaigns or ad groups | Account ID, target resource name, negative keyword list |
| `update_budget_amount` | Updates the daily amount of an existing budget | Account ID, budget resource name, new daily amount |
### **How to Create a Complete Campaign Setup**
With the new write tools, you can now create complete Google Ads campaigns through Claude! Here's the recommended workflow:
#### **Step 1: Plan Your Campaign**
Ask Claude to help you plan your campaign structure:
- "Help me plan a campaign structure for selling running shoes with a $100 daily budget"
#### **Step 2: Create the Foundation**
1. **Create a budget first:**
- "Create a campaign budget named 'Running Shoes Budget' with $100 daily spend for account 1234567890"
2. **Create the campaign:**
- "Create a search campaign named 'Running Shoes Campaign' using the budget we just created"
#### **Step 3: Build Ad Groups and Content**
3. **Create ad groups:**
- "Create an ad group called 'Men's Running Shoes' in the campaign we just created with $2.00 max CPC"
4. **Add keywords:**
- "Add these keywords to the ad group: 'running shoes' (exact), 'men's running shoes' (phrase), 'athletic footwear' (broad)"
5. **Create responsive search ads:**
- "Create a responsive search ad with headlines: 'Best Running Shoes', 'Free Shipping', 'Shop Now' and descriptions: 'Find your perfect pair today', 'Wide selection available'"
#### **Step 4: Add Negative Keywords**
6. **Add negative keywords:**
- "Add negative keywords 'free', 'cheap', 'used' to the campaign to prevent irrelevant traffic"
#### **Step 5: Enable When Ready**
7. **Enable everything:**
- "Enable the campaign, ad group, keywords, and ads when I'm ready to start spending"
#### **Example Complete Setup Conversation:**
```
You: "Help me create a complete Google Ads campaign for my online shoe store. I want to spend $50 per day targeting people looking for running shoes."
Claude: I'll help you create a complete campaign setup! Let me start by creating the budget and campaign structure.
[Claude uses the tools to:]
1. Create a $50 daily budget
2. Create a search campaign
3. Create focused ad groups
4. Add relevant keywords with appropriate bids
5. Create compelling responsive search ads
6. Add negative keywords to prevent irrelevant traffic
7. Keep everything paused until you're ready to launch
You: "Great! Now enable everything so the campaign starts running."
Claude: [Uses update tools to enable the campaign, ad groups, keywords, and ads]
All set! Your campaign is now live and will start showing ads to people searching for running shoes.
```
### 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
```sql
SELECT
campaign.name,
metrics.clicks,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_7DAYS
```
### Example 2: Ad group performance
```sql
SELECT
ad_group.name,
metrics.conversions,
metrics.cost_micros
FROM ad_group
WHERE metrics.clicks > 100
```
### Example 3: Keyword analysis
```sql
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](https://console.cloud.google.com/)
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](https://console.cloud.google.com/)
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](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](https://www.python.org/downloads/) (version 3.11 or newer) - This runs the connection between Google Ads and Claude
- [Node.js](https://nodejs.org/en) - Required for running the MCP inspector and certain MCP components
- [Claude Desktop](https://claude.ai/download) - 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:
```bash
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
```
2. 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.
3. Activate the virtual environment:
```bash
# On Mac/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate
```
4. 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
```
2. 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
```
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
```json
{
"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
```json
{
"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](https://claude.ai/download) 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:
```bash
# 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):
```json
{
"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](https://cursor.sh/)
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:
```json
{
"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:
#### **Analysis & Reporting Prompts**
| **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%'" |
#### **Campaign Creation & Management Prompts** ✨ NEW!
| **Use Case** | **Sample Prompt** |
|---------------------------------|--------------------------------------------------------------------------------------------------|
| **Complete Campaign Setup** | "Create a complete Google Ads campaign for my fitness app. I want to spend $200/day targeting people searching for 'workout apps' and 'fitness tracking'. Include relevant keywords, compelling ads, and negative keywords." |
| **Budget Management** | "Create a shared budget of $150/day called 'E-commerce Budget' that I can use across multiple campaigns." |
| **Campaign Creation** | "Create a search campaign called 'Brand Defense' using the budget we just created. Start it paused so I can review before launching." |
| **Keyword Expansion** | "Add these high-intent keywords to my 'Running Shoes' ad group: 'buy running shoes online', 'best marathon shoes', 'trail running footwear' with appropriate match types and $3 max CPC bids." |
| **Ad Creation** | "Create a responsive search ad for my software product with headlines focusing on benefits like 'Save Time', 'Increase Productivity', and 'Free Trial' plus compelling descriptions." |
| **Negative Keywords** | "Add negative keywords to my campaign to exclude searches for 'free', 'pirated', 'crack', and 'torrent' to improve traffic quality." |
| **Campaign Optimization** | "Update my 'Holiday Sale' campaign budget from $50 to $150 daily since it's performing well." |
| **Status Management** | "Enable all the campaigns, ad groups, and keywords we just created so they start running." |
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):
```bash
# 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:
```bash
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:
```bash
# 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:
```bash
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:
```bash
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](mailto:ernesto@ixigo.com).
---
## License
This project is licensed under the MIT License. See the [LICENSE](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](https://www.ixigo.com).
<img src="ixigo-logo.png" alt="ixigo logo" width="200px" />
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-google-ads",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mcp, google ads, seo, sem, claude, search analytics, campaign management, automation",
"author": null,
"author_email": "Ernesto Cohnen <ernesto@ixigo.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/54/a3b75cae1ef378e4591c3b1d3b01a59db533450c63203d2a8044423803cc/mcp_google_ads-0.2.3.tar.gz",
"platform": null,
"description": "# Google Ads MCP\n\n\n\nA tool that connects [Google Ads](https://ads.google.com/) 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\u2014all through simple chat with Claude.\n\n---\n\n## What Can This Tool Do For Advertising Professionals?\n\n1. **Account Management** \n - See all your Google Ads accounts in one place\n - Get account details and basic campaign information\n\n2. **Campaign Analytics & Reporting** \n - Discover which campaigns are performing best\n - Track impressions, clicks, conversions, and cost metrics\n - Analyze performance trends over time\n - Compare different time periods to spot changes\n - **Visualize your data** with charts and graphs created by Claude\n\n3. **Keyword & Ad Performance** \n - Identify top and underperforming keywords\n - Analyze ad copy effectiveness \n - Check quality scores and competitive metrics\n - Get actionable insights on how to improve your campaigns\n\n4. **Budget & Bid Management** \n - Monitor campaign budgets and spending\n - Analyze bid strategies and performance\n - Identify opportunities for optimization\n - Get recommendations for budget allocation\n\n---\n\n## Google Ads MCP Architecture Flow\n\n```mermaid\nflowchart TB\n User(User) -->|Interacts with| Claude\n Claude(Claude AI Assistant) -->|Makes requests to| MCP[Google Ads MCP Server]\n User -->|Can also use| Cursor[Cursor AI Code Editor]\n Cursor -->|Makes requests to| MCP\n \n subgraph \"MCP Server\"\n FastMCP[FastMCP Server] \n Tools[Available Tools]\n Auth[Authentication]\n \n FastMCP -->|Exposes| Tools\n FastMCP -->|Uses| Auth\n end\n \n subgraph \"Google Ads Tools\"\n ListAccounts[list_accounts]\n ExecuteGAQL[execute_gaql_query]\n CampaignPerf[get_campaign_performance]\n AdPerf[get_ad_performance]\n RunGAQL[run_gaql]\n end\n \n Tools -->|Includes| ListAccounts\n Tools -->|Includes| ExecuteGAQL\n Tools -->|Includes| CampaignPerf\n Tools -->|Includes| AdPerf\n Tools -->|Includes| RunGAQL\n \n subgraph \"Authentication\"\n OAuth[OAuth 2.0 Client ID]\n ServiceAccount[Service Account]\n Credentials[Google Ads API Credentials]\n \n OAuth -->|Provides| Credentials\n ServiceAccount -->|Provides| Credentials\n end\n \n MCP -->|Communicates with| GoogleAdsAPI[Google Ads API]\n GoogleAdsAPI -->|Returns| AdData[Advertising Data]\n AdData -->|Analyzed by| Claude\n AdData -->|Visualized by| Claude\n AdData -->|Can be used by| Cursor\n \n Credentials -->|Authorizes| GoogleAdsAPI\n \n subgraph \"Configuration\"\n EnvVars[Environment Variables]\n ConfigFiles[Configuration Files]\n \n EnvVars -->|Configures| MCP\n ConfigFiles -->|Configures| Claude\n ConfigFiles -->|Configures| Cursor\n end\n```\n\n## Available Tools\n\nHere's what you can ask Claude to do once you've set up this integration:\n\n### **Read/Analysis Tools**\n\n| **What You Can Ask For** | **What It Does** | **What You'll Need to Provide** |\n|---------------------------------|-------------------------------------------------------------|----------------------------------------------------------------|\n| `list_accounts` | Shows all your Google Ads accounts | Nothing - just ask! |\n| `execute_gaql_query` | Runs a Google Ads Query Language query | Your account ID and a GAQL query |\n| `get_campaign_performance` | Shows campaign metrics with performance data | Your account ID and time period |\n| `get_ad_performance` | Detailed analysis of your ad creative performance | Your account ID and time period |\n| `run_gaql` | Runs any arbitrary GAQL query with formatting options | Your account ID, query, and format (table, JSON, or CSV) |\n| `get_ad_creatives` | Retrieves ad copy, headlines, and descriptions | Your account ID |\n| `get_account_currency` | Shows the account's default currency | Your account ID |\n| `get_image_assets` | Lists image assets with download URLs | Your account ID |\n| `download_image_asset` | Downloads specific image assets | Your account ID and asset ID |\n| `get_asset_usage` | Shows where assets are used in campaigns | Your account ID and optional asset ID |\n| `analyze_image_assets` | Performance analysis of image assets | Your account ID and time period |\n\n### **Write/Management Tools** \u2728 NEW!\n\n| **What You Can Ask For** | **What It Does** | **What You'll Need to Provide** |\n|---------------------------------|-------------------------------------------------------------|----------------------------------------------------------------|\n| `create_campaign_budget` | Creates a new campaign budget | Account ID, budget name, daily amount |\n| `create_campaign` | Creates a new Google Ads campaign | Account ID, campaign name, budget resource name |\n| `update_campaign_status` | Enable, pause, or remove campaigns | Account ID, campaign resource name, new status |\n| `update_campaign_budget` | Change which budget a campaign uses | Account ID, campaign resource name, new budget resource name |\n| `create_ad_group` | Creates a new ad group within a campaign | Account ID, ad group name, campaign resource name, CPC bid |\n| `add_keywords` | Adds keywords to an ad group | Account ID, ad group resource name, keyword list with bids |\n| `update_keyword_status` | Enable, pause, or remove keywords | Account ID, keyword resource names, new status |\n| `create_responsive_search_ad` | Creates responsive search ads with headlines/descriptions | Account ID, ad group resource name, headlines, descriptions, URLs |\n| `add_negative_keywords` | Adds negative keywords to campaigns or ad groups | Account ID, target resource name, negative keyword list |\n| `update_budget_amount` | Updates the daily amount of an existing budget | Account ID, budget resource name, new daily amount |\n\n### **How to Create a Complete Campaign Setup**\n\nWith the new write tools, you can now create complete Google Ads campaigns through Claude! Here's the recommended workflow:\n\n#### **Step 1: Plan Your Campaign**\nAsk Claude to help you plan your campaign structure:\n- \"Help me plan a campaign structure for selling running shoes with a $100 daily budget\"\n\n#### **Step 2: Create the Foundation**\n1. **Create a budget first:**\n - \"Create a campaign budget named 'Running Shoes Budget' with $100 daily spend for account 1234567890\"\n\n2. **Create the campaign:**\n - \"Create a search campaign named 'Running Shoes Campaign' using the budget we just created\"\n\n#### **Step 3: Build Ad Groups and Content**\n3. **Create ad groups:**\n - \"Create an ad group called 'Men's Running Shoes' in the campaign we just created with $2.00 max CPC\"\n\n4. **Add keywords:**\n - \"Add these keywords to the ad group: 'running shoes' (exact), 'men's running shoes' (phrase), 'athletic footwear' (broad)\"\n\n5. **Create responsive search ads:**\n - \"Create a responsive search ad with headlines: 'Best Running Shoes', 'Free Shipping', 'Shop Now' and descriptions: 'Find your perfect pair today', 'Wide selection available'\"\n\n#### **Step 4: Add Negative Keywords**\n6. **Add negative keywords:**\n - \"Add negative keywords 'free', 'cheap', 'used' to the campaign to prevent irrelevant traffic\"\n\n#### **Step 5: Enable When Ready**\n7. **Enable everything:**\n - \"Enable the campaign, ad group, keywords, and ads when I'm ready to start spending\"\n\n#### **Example Complete Setup Conversation:**\n\n```\nYou: \"Help me create a complete Google Ads campaign for my online shoe store. I want to spend $50 per day targeting people looking for running shoes.\"\n\nClaude: I'll help you create a complete campaign setup! Let me start by creating the budget and campaign structure.\n\n[Claude uses the tools to:]\n1. Create a $50 daily budget\n2. Create a search campaign \n3. Create focused ad groups\n4. Add relevant keywords with appropriate bids\n5. Create compelling responsive search ads\n6. Add negative keywords to prevent irrelevant traffic\n7. Keep everything paused until you're ready to launch\n\nYou: \"Great! Now enable everything so the campaign starts running.\"\n\nClaude: [Uses update tools to enable the campaign, ad groups, keywords, and ads]\n\nAll set! Your campaign is now live and will start showing ads to people searching for running shoes.\n```\n\n### Using the Advanced Query Tools\n\nThe `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:\n\n### Example 1: Basic campaign metrics\n\n```sql\nSELECT \n campaign.name, \n metrics.clicks, \n metrics.impressions \nFROM campaign \nWHERE segments.date DURING LAST_7DAYS\n```\n\n### Example 2: Ad group performance\n\n```sql\nSELECT \n ad_group.name, \n metrics.conversions, \n metrics.cost_micros \nFROM ad_group \nWHERE metrics.clicks > 100\n```\n\n### Example 3: Keyword analysis\n\n```sql\nSELECT \n keyword.text, \n metrics.average_position, \n metrics.ctr \nFROM keyword_view \nORDER BY metrics.impressions DESC\n```\n\n*For a complete list of all available tools and their detailed descriptions, ask Claude to \"list tools\" after setup.*\n\n---\n\n## Getting Started (No Coding Experience Required!)\n\n### 1. Set Up Google Ads API Access\n\nBefore 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:\n\n#### Option A: OAuth 2.0 Client ID (User Authentication)\n\nBest for individual users or desktop applications:\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select an existing one\n3. Enable the Google Ads API\n4. Go to \"Credentials\" \u2192 \"Create Credentials\" \u2192 \"OAuth Client ID\"\n5. Choose \"Desktop Application\" as the application type\n6. Download the OAuth client configuration file (client_secret.json)\n7. Create a Google Ads API Developer token (see below)\n\n#### Option B: Service Account (Server-to-Server Authentication)\n\nBetter for automated systems or managing multiple accounts:\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select an existing one\n3. Enable the Google Ads API\n4. Go to \"Credentials\" \u2192 \"Create Credentials\" \u2192 \"Service Account\"\n5. Download the service account key file (JSON)\n6. Grant the service account access to your Google Ads accounts\n7. Create a Google Ads API Developer token (see below)\n\n#### Authentication Token Refreshing\n\nThe application now includes robust token refresh handling:\n\n- **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.\n- **Service Account Tokens**: Service account tokens are automatically generated and refreshed as needed without user intervention.\n\n#### Authentication Method Comparison\n\nChoose OAuth 2.0 Client ID if:\n\n- You're building a desktop application\n- Users need to explicitly grant access\n- You're managing a single account or a few personal accounts\n- You want users to have control over access permissions\n\nChoose Service Account if:\n\n- You're building an automated system\n- You need server-to-server authentication\n- You're managing multiple accounts programmatically\n- You don't want/need user interaction for authentication\n- You need automatic token refreshing without user intervention\n\n#### Getting a Developer Token\n\n1. Sign in to your Google Ads account at [https://ads.google.com](https://ads.google.com)\n2. Click on Tools & Settings (wrench icon) in the top navigation\n3. Under \"Setup\", click \"API Center\"\n4. If you haven't already, accept the Terms of Service\n5. Click \"Apply for token\" \n6. Fill out the application form with details about how you plan to use the API\n7. Submit the application and wait for approval (usually 1-3 business days)\n\nNote: 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.\n\n### Understanding the Login Customer ID\n\nThe `GOOGLE_ADS_LOGIN_CUSTOMER_ID` is optional and is primarily used when:\n\n- You're working with a Google Ads Manager Account (MCC)\n- You need to access multiple client accounts under that manager account\n\nThe Login Customer ID should be your Manager Account ID (format: XXX-XXX-XXXX) if:\n\n- You're accessing multiple accounts under a manager account\n- You want to use manager account credentials to access client accounts\n\nYou can skip this setting if:\n\n- You're only accessing a single Google Ads account\n- You're using credentials directly from the account you want to access\n\nTo find your Manager Account ID:\n\n1. Sign in to your Google Ads Manager Account\n2. Click on the settings icon (gear)\n3. Your Manager Account ID will be displayed in the format XXX-XXX-XXXX\n4. Download the credentials file (a JSON file)\n\n**\ud83c\udfac Watch this beginner-friendly tutorial on Youtube:**\nCOMING SOON\n\n### 2. Install Required Software\n\nYou'll need to install these tools on your computer:\n\n- [Python](https://www.python.org/downloads/) (version 3.11 or newer) - This runs the connection between Google Ads and Claude\n- [Node.js](https://nodejs.org/en) - Required for running the MCP inspector and certain MCP components\n- [Claude Desktop](https://claude.ai/download) - The AI assistant you'll chat with\n\nMake sure both Python and Node.js are properly installed and available in your system path before proceeding.\n\n### 3. Download the Google Ads MCP \n\nYou need to download this tool to your computer. The easiest way is:\n\n1. Click the green \"Code\" button at the top of this page\n2. Select \"Download ZIP\"\n3. Unzip the downloaded file to a location you can easily find (like your Documents folder)\n\nAlternatively, if you're familiar with Git:\n\n```bash\ngit clone https://github.com/ixigo/mcp-google-ads.git\n```\n\n### 4. Install Required Components\n\nOpen your computer's Terminal (Mac) or Command Prompt (Windows):\n\n1. Navigate to the folder where you unzipped the files:\n\n ```bash\n # Example (replace with your actual path):\n cd ~/Documents/mcp-google-ads-main\n ```\n\n2. Create a virtual environment (this keeps the project dependencies isolated):\n\n ```bash\n # Using uv (recommended):\n uv venv .venv\n \n # If uv is not installed, install it first:\n pip install uv\n # Then create the virtual environment:\n uv venv .venv\n\n # OR using standard Python:\n python -m venv .venv\n ```\n\n **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.\n\n3. Activate the virtual environment:\n\n ```bash\n # On Mac/Linux:\n source .venv/bin/activate\n \n # On Windows:\n .venv\\Scripts\\activate\n ```\n\n4. Install the required dependencies:\n\n ```bash\n # Using uv:\n uv pip install -r requirements.txt\n\n # OR using standard pip:\n pip install -r requirements.txt\n \n # If you encounter any issues with the MCP package, install it separately:\n pip install mcp\n ```\n\n **If you get \"pip not found\" error:**\n\n ```bash\n # First ensure pip is installed and updated:\n python3 -m ensurepip --upgrade\n python3 -m pip install --upgrade pip\n \n # Then try installing the requirements again:\n python3 -m pip install -r requirements.txt\n \n # Or to install uv:\n python3 -m pip install uv\n ```\n\nWhen 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.\n\n### 5. Setting Up Environment Configuration\n\nThe Google Ads MCP now supports environment file configuration for easier setup.\n\n#### Using .env File (Recommended)\n\n1. Copy the `.env.example` file to `.env` in your project directory:\n\n ```bash\n cp .env.example .env\n ```\n\n2. Edit the `.env` file with your actual configuration values:\n\n ```bash\n # Edit the .env file with your favorite text editor\n # For Mac:\n nano .env\n \n # For Windows:\n notepad .env\n ```\n\n3. Set the following values in your `.env` file:\n\n ```\n # Authentication Type: \"oauth\" or \"service_account\"\n GOOGLE_ADS_AUTH_TYPE=oauth\n \n # Path to your credentials file (OAuth client secret or service account key)\n GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json\n \n # Your Google Ads Developer Token\n GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here\n \n # Optional: Manager Account ID (if applicable)\n GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id\n ```\n\n4. Save the file.\n\nThe application will automatically load these values from the `.env` file when it starts.\n\n#### Using Direct Environment Variables\n\nYou can also set environment variables directly in your system or in the configuration files for Claude or Cursor:\n\n##### For Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"googleAdsServer\": {\n \"command\": \"/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python\",\n \"args\": [\"/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py\"],\n \"env\": {\n \"GOOGLE_ADS_AUTH_TYPE\": \"oauth\",\n \"GOOGLE_ADS_CREDENTIALS_PATH\": \"/FULL/PATH/TO/mcp-google-ads-main/credentials.json\",\n \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n }\n }\n }\n}\n```\n\n##### For Cursor\n\n```json\n{\n \"mcpServers\": {\n \"googleAdsServer\": {\n \"command\": \"/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python\",\n \"args\": [\"/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py\"],\n \"env\": {\n \"GOOGLE_ADS_AUTH_TYPE\": \"oauth\",\n \"GOOGLE_ADS_CREDENTIALS_PATH\": \"/FULL/PATH/TO/mcp-google-ads-main/credentials.json\",\n \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n }\n }\n }\n}\n```\n\n### 6. Connect Claude to Google Ads\n\n1. Download and install [Claude Desktop](https://claude.ai/download) if you haven't already\n2. Make sure you have your Google service account credentials file saved somewhere on your computer\n3. Open your computer's Terminal (Mac) or Command Prompt (Windows) and type:\n\n```bash\n# For Mac users:\nnano ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n\n# For Windows users:\nnotepad %APPDATA%\\Claude\\claude_desktop_config.json\n```\n\nAdd the following text (this tells Claude how to connect to Google Ads):\n\n```json\n{\n \"mcpServers\": {\n \"googleAdsServer\": {\n \"command\": \"/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python\",\n \"args\": [\"/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py\"],\n \"env\": {\n \"GOOGLE_ADS_CREDENTIALS_PATH\": \"/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json\",\n \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n }\n }\n }\n}\n```\n\n**Important:** Replace all paths and values with the actual information for your account:\n\n- The first path should point to the Python executable inside your virtual environment\n- The second path should point to the `google_ads_server.py` file inside the folder you unzipped\n- The third path should point to your Google service account credentials JSON file\n- Add your Google Ads Developer Token \n- Add your Google Ads Manager Account ID (if applicable)\n\nExamples:\n\n- Mac: \n - Python path: `/Users/ernesto/Documents/mcp-google-ads/.venv/bin/python`\n - Script path: `/Users/ernesto/Documents/mcp-google-ads/google_ads_server.py`\n- Windows: \n - Python path: `C:\\\\Users\\\\ernesto\\\\Documents\\\\mcp-google-ads\\\\.venv\\\\Scripts\\\\python.exe`\n - Script path: `C:\\\\Users\\\\ernesto\\\\Documents\\\\mcp-google-ads\\\\google_ads_server.py`\n\n4. Save the file:\n\n - Mac: Press Ctrl+O, then Enter, then Ctrl+X to exit\n - Windows: Click File > Save, then close Notepad\n\n5. Restart Claude Desktop\n\n6. When Claude opens, you should now see Google Ads tools available in the tools section\n\n### 5a. Connect to Cursor (AI Code Editor)\n\nCursor 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.\n\n#### Setting Up Cursor Integration\n\n1. If you haven't already, download and install [Cursor](https://cursor.sh/) \n2. Create a Cursor MCP configuration file:\n\n **For project-specific configuration:**\n Create a `.cursor/mcp.json` file in your project directory.\n\n **For global configuration (available in all projects):**\n Create a `~/.cursor/mcp.json` file in your home directory.\n\n3. Add the following configuration to your MCP config file:\n\n ```json\n {\n \"mcpServers\": {\n \"googleAdsServer\": {\n \"command\": \"/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python\",\n \"args\": [\"/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py\"],\n \"env\": {\n \"GOOGLE_ADS_CREDENTIALS_PATH\": \"/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json\",\n \"GOOGLE_ADS_DEVELOPER_TOKEN\": \"YOUR_DEVELOPER_TOKEN_HERE\",\n \"GOOGLE_ADS_LOGIN_CUSTOMER_ID\": \"YOUR_MANAGER_ACCOUNT_ID_HERE\"\n }\n }\n }\n }\n ```\n\n **Important:** Replace all paths and values with the actual information for your account, just like in the Claude Desktop configuration.\n\n4. Restart Cursor or reload the workspace to apply the new configuration.\n\n5. The Google Ads MCP will now appear in Cursor's \"Available Tools\" section and can be used by Cursor's AI agent when needed.\n\n#### Using Google Ads MCP in Cursor\n\nWhen working in Cursor, you can ask the AI agent to use the Google Ads tools directly. For example:\n\n- \"Use the Google Ads MCP to list all my accounts and show me which ones have the highest spend.\"\n- \"Can you analyze my campaign performance for the last 30 days using the Google Ads MCP?\"\n- \"Run a GAQL query to find my top converting keywords using the Google Ads tools.\"\n\nCursor will prompt you to approve the tool usage (unless you've enabled Yolo mode) and then display the results directly in the chat interface.\n\n#### Cursor-Specific Features\n\nWhen using the Google Ads MCP with Cursor, you can:\n\n1. **Combine Code and Ads Analysis**: Ask Cursor to analyze your marketing-related code alongside actual campaign performance data.\n2. **Generate Data Visualizations**: Request charts and visualizations of your ad performance directly in your development environment.\n3. **Implement Recommendations**: Let Cursor suggest code improvements based on your actual advertising data.\n\nThis integration is particularly valuable for developers working on marketing automation, analytics dashboards, or e-commerce applications where ad performance directly impacts code decisions.\n\n### 6. Start Analyzing Your Advertising Data!\n\nNow 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.\n\nHere are some powerful prompts you can use with each tool:\n\n#### **Analysis & Reporting Prompts**\n\n| **Tool Name** | **Sample Prompt** |\n|---------------------------------|--------------------------------------------------------------------------------------------------|\n| `list_accounts` | \"List all my Google Ads accounts and tell me which ones have the highest spend this month.\" |\n| `execute_gaql_query` | \"Execute this query for account 123-456-7890: SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000\" |\n| `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.\" |\n| `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.\" |\n| `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%'\" |\n\n#### **Campaign Creation & Management Prompts** \u2728 NEW!\n\n| **Use Case** | **Sample Prompt** |\n|---------------------------------|--------------------------------------------------------------------------------------------------|\n| **Complete Campaign Setup** | \"Create a complete Google Ads campaign for my fitness app. I want to spend $200/day targeting people searching for 'workout apps' and 'fitness tracking'. Include relevant keywords, compelling ads, and negative keywords.\" |\n| **Budget Management** | \"Create a shared budget of $150/day called 'E-commerce Budget' that I can use across multiple campaigns.\" |\n| **Campaign Creation** | \"Create a search campaign called 'Brand Defense' using the budget we just created. Start it paused so I can review before launching.\" |\n| **Keyword Expansion** | \"Add these high-intent keywords to my 'Running Shoes' ad group: 'buy running shoes online', 'best marathon shoes', 'trail running footwear' with appropriate match types and $3 max CPC bids.\" |\n| **Ad Creation** | \"Create a responsive search ad for my software product with headlines focusing on benefits like 'Save Time', 'Increase Productivity', and 'Free Trial' plus compelling descriptions.\" |\n| **Negative Keywords** | \"Add negative keywords to my campaign to exclude searches for 'free', 'pirated', 'crack', and 'torrent' to improve traffic quality.\" |\n| **Campaign Optimization** | \"Update my 'Holiday Sale' campaign budget from $50 to $150 daily since it's performing well.\" |\n| **Status Management** | \"Enable all the campaigns, ad groups, and keywords we just created so they start running.\" |\n\nYou can also ask Claude to combine multiple tools and analyze the results. For example:\n\n- \"Find my top 20 converting keywords, check their quality scores and impression share, and create a report highlighting opportunities for scaling.\"\n\n- \"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.\"\n\n- \"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.\"\n\n- \"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.\"\n\nClaude 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.\n\n---\n\n## Data Visualization Capabilities\n\nClaude can help you visualize your Google Ads data in various ways:\n\n- **Trend Charts**: See how metrics change over time\n- **Comparison Graphs**: Compare different campaigns or ad groups\n- **Performance Distributions**: Understand how your ads perform across devices or audiences\n- **Correlation Analysis**: Identify relationships between spend and conversion metrics\n- **Heatmaps**: Visualize complex datasets with color-coded representations\n\nSimply 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.\n\n---\n\n## Troubleshooting\n\n### Python Command Not Found\n\nOn macOS, the default Python command is often `python3` rather than `python`, which can cause issues with some applications including Node.js integrations.\n\nIf you encounter errors related to Python not being found, you can create an alias:\n\n1. Create a Python alias (one-time setup):\n ```bash\n # For macOS users:\n sudo ln -s $(which python3) /usr/local/bin/python\n \n # If that doesn't work, try finding your Python installation:\n sudo ln -s /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 /usr/local/bin/python\n ```\n\n2. Verify the alias works:\n\n ```bash\n python --version\n ```\n\nThis creates a symbolic link so that when applications call `python`, they'll actually use your `python3` installation.\n\n### Claude Configuration Issues\n\nIf you're having trouble connecting:\n\n1. Make sure all file paths in your configuration are correct and use the full path\n2. Check that your service account has access to your Google Ads accounts\n3. Verify that your Developer Token is valid and correctly entered\n4. Restart Claude Desktop after making any changes\n5. Look for error messages in Claude's response when you try to use a tool\n6. Ensure your virtual environment is activated when running the server manually\n\n### Google Ads API Limitations\n\nIf you encounter issues related to API quotas or permissions:\n\n1. Check your Google Ads API quota limits in the Google Cloud Console\n2. Ensure your Developer Token has the appropriate access level\n3. Verify that you've granted the proper permissions to your service account\n\n### Other Unexpected Issues\n\nIf you encounter any other unexpected issues during installation or usage:\n\n1. Copy the exact error message you're receiving\n2. Contact Ernesto Cohnen at ernesto@ixigo.com for support, including:\n - What you were trying to do\n - The exact error message\n - Your operating system\n - Any steps you've already tried\n\nYou can also consult AI assistants which can often help diagnose and resolve technical issues by suggesting specific solutions for your situation.\n\nRemember that most issues have been encountered by others before, and there's usually a straightforward solution available.\n\n### Testing Your Setup\n\nThe repository includes test files that let you verify your Google Ads API connection is working correctly before using it with Claude or Cursor.\n\n#### Testing Basic Functionality\n\n1. Make sure your virtual environment is activated:\n\n ```bash\n # On Mac/Linux:\n source .venv/bin/activate\n \n # On Windows:\n .venv\\Scripts\\activate\n ```\n\n2. Configure the environment variables in the test file or set them in your environment:\n - Open `test_google_ads_mcp.py` in a text editor\n - Find the section starting with `if not os.environ.get(\"GOOGLE_ADS_CREDENTIALS_PATH\"):`\n - Update the placeholder values with your actual credentials or comment out this section if you've set them as environment variables\n\n3. Run the test:\n ```bash\n python test_google_ads_mcp.py\n ```\n\n4. The test will:\n - List all your Google Ads accounts\n - Use the first account ID to test campaign performance retrieval\n - Test ad performance data\n - Retrieve ad creatives\n - Run a sample GAQL query\n\n#### Testing Authentication and Token Refresh\n\nTo specifically test the authentication and token refresh mechanisms:\n\n1. Make sure your virtual environment is activated and your `.env` file is configured.\n\n2. Run the token refresh test:\n ```bash\n python test_token_refresh.py\n ```\n\n3. This test will:\n - Verify that credentials can be loaded from your configured auth type (OAuth or service account)\n - Display information about the current token status and expiry\n - Test the customer ID formatting function\n - For OAuth tokens, attempt to refresh the token and verify it worked\n\nThe token refresh test can help confirm that both OAuth and service account credentials are properly configured before using the server with Claude or Cursor.\n \nIf all tests complete successfully, your setup is working correctly and ready to use with Claude or Cursor.\n\n---\n\n## Contributing\n\nFound 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](mailto:ernesto@ixigo.com).\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## About ixigo\n\nixigo 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](https://www.ixigo.com).\n\n<img src=\"ixigo-logo.png\" alt=\"ixigo logo\" width=\"200px\" />\n\nixigo 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.\n",
"bugtrack_url": null,
"license": null,
"summary": "Google Ads API integration for Model Context Protocol (MCP) with full campaign management capabilities",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/cohnen/mcp-google-ads/issues",
"Homepage": "https://github.com/cohnen/mcp-google-ads"
},
"split_keywords": [
"mcp",
" google ads",
" seo",
" sem",
" claude",
" search analytics",
" campaign management",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8fafc6edcca801ff1a026220d768e544e3ec897c2471650bae8363b7bd26f669",
"md5": "fa1af45d93b8b1fbb0b2746b8356dcb4",
"sha256": "58b37588001e1295a1d74008256cfbd274929132140891c12b6a78e0883bc611"
},
"downloads": -1,
"filename": "mcp_google_ads-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa1af45d93b8b1fbb0b2746b8356dcb4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 32222,
"upload_time": "2025-07-08T21:09:00",
"upload_time_iso_8601": "2025-07-08T21:09:00.363071Z",
"url": "https://files.pythonhosted.org/packages/8f/af/c6edcca801ff1a026220d768e544e3ec897c2471650bae8363b7bd26f669/mcp_google_ads-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0d54a3b75cae1ef378e4591c3b1d3b01a59db533450c63203d2a8044423803cc",
"md5": "da10b262152681dc1574bcf48f553413",
"sha256": "f9c090e372ed61ec3a2fe9c0f555f0f59c11f31ea5a025dc47a7f41dda8c4035"
},
"downloads": -1,
"filename": "mcp_google_ads-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "da10b262152681dc1574bcf48f553413",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 51802,
"upload_time": "2025-07-08T21:09:01",
"upload_time_iso_8601": "2025-07-08T21:09:01.502204Z",
"url": "https://files.pythonhosted.org/packages/0d/54/a3b75cae1ef378e4591c3b1d3b01a59db533450c63203d2a8044423803cc/mcp_google_ads-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 21:09:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cohnen",
"github_project": "mcp-google-ads",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"0.0.11"
]
]
},
{
"name": "google-auth",
"specs": [
[
">=",
"2.25.2"
]
]
},
{
"name": "google-auth-oauthlib",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "google-auth-httplib2",
"specs": [
[
">=",
"0.1.1"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.7.3"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.1.4"
]
]
}
],
"lcname": "mcp-google-ads"
}
JSON
