Google Ads
STDIOMCP server for accessing Google Ads data through Claude Desktop with visualization capabilities.
MCP server for accessing Google Ads data through Claude Desktop with visualization capabilities.
Updated on May 22, 2025 - Phase 5 Automated Insights Features Implementation Complete
A Model Context Protocol (MCP) server that provides access to Google Ads data through Claude Desktop.
This repository implements the Project Quantum Pulse roadmap for enhanced Google Ads management capabilities:
Clone this repository:
git clone https://github.com/yourusername/google-ads-mcp.git
cd google-ads-mcp
Set up a virtual environment:
python -m venv .venv
source .venv/bin/activate # On Windows, use: .venv\Scripts\activate
Install dependencies:
pip install -r requirements.txt
Create a .env file with your Google Ads credentials:
cp .env.example .env
# Edit .env file with your credentials
Run the server:
python server.py
Build the Docker image:
docker build -t google-ads-mcp:latest .
Run the container:
docker run -p 8000:8000 --env-file .env google-ads-mcp:latest
Alternatively, use docker-compose:
docker-compose up -d
The application supports different environments (dev, test, prod) with environment-specific configurations:
APP_ENV to dev, test, or prod to specify the environment.env.exampleConfigure Claude Desktop for the MCP server in your Claude Desktop App configuration:
{ "mcpServers": { "google-ads": { "command": "python", "args": [ "/absolute/path/to/server.py" ] } } }
Restart Claude Desktop and look for the tools icon to appear
Use Google Ads data in Claude by asking questions like:
The following MCP tools are available for ad group management:
| Tool | Description |
|---|---|
get_ad_groups | Get ad groups for a Google Ads account with optional filtering |
get_ad_groups_json | Get ad groups in JSON format for visualization |
get_ad_group_performance | Get performance metrics for a specific ad group |
get_ad_group_performance_json | Get ad group performance metrics in JSON format for visualization |
create_ad_group | Create a new ad group within a campaign |
update_ad_group | Update an existing ad group's attributes |
The following MCP tools are available for keyword management:
| Tool | Description |
|---|---|
get_keywords | Get keywords for a Google Ads account with optional filtering |
get_keywords_json | Get keywords in JSON format for visualization |
add_keywords | Add a new keyword to an ad group |
update_keyword | Update an existing keyword's status or bid |
remove_keywords | Remove keywords from an ad group |
get_search_terms_report | View search terms that triggered your ads |
get_search_terms_report_json | Get search terms in JSON format for visualization |
analyze_search_terms | Get insights about your search terms performance |
analyze_search_terms_json | Get insights about your search terms performance in JSON format for visualization |
Example usage in Claude:
The following MCP tools are available for budget management:
| Tool | Description |
|---|---|
get_budgets | Get campaign budgets with performance metrics and utilization |
get_budgets_json | Get budget information in JSON format with visualizations |
analyze_budgets | Analyze budget performance with insights and recommendations |
update_budget | Update a budget's amount or delivery method (placeholder implementation) |
Example usage in Claude:
Example response for get_budgets:
Budget Report (3 budgets found)
ID: 123456789
Name: Search Campaign Budget
Amount: 50.00 USD (Daily)
Status: ENABLED
Utilization: 65.4%
Associated Campaigns: Brand Search, Generic Search
ID: 987654321
Name: Display Campaign Budget
Amount: 100.00 USD (Daily)
Status: ENABLED
Utilization: 94.2%
Associated Campaigns: Retargeting Display, Prospecting Display
ID: 456789123
Name: Shopping Campaign Budget
Amount: 75.00 USD (Daily)
Status: ENABLED
Utilization: 32.1%
Associated Campaigns: Product Shopping
Example response for analyze_budgets:
Budget Analysis Report
Budget: Display Campaign Budget (ID: 987654321)
Amount: 100.00 USD (Daily)
Utilization: 94.2%
Associated Campaigns: Retargeting Display, Prospecting Display
Insights:
- High Utilization (94.2%)
- Budget nearly depleted before day end
Recommendations:
- Consider increasing budget to 120.00 USD
- Or reduce bid adjustments during peak hours
Budget: Search Campaign Budget (ID: 123456789)
Amount: 50.00 USD (Daily)
Utilization: 65.4%
Associated Campaigns: Brand Search, Generic Search
Insights:
- Moderate Utilization (65.4%)
- Performing well within budget constraints
Recommendations:
- Monitor performance
- Consider reallocating budget to high-performing campaigns
Budget: Shopping Campaign Budget (ID: 456789123)
Amount: 75.00 USD (Daily)
Utilization: 32.1%
Associated Campaigns: Product Shopping
Insights:
- Low Utilization (32.1%)
- Budget consistently underutilized
Recommendations:
- Consider reducing budget to 50.00 USD
- Or reallocate budget to higher-performing campaigns
The following MCP tools provide rich data visualization and advanced analysis capabilities:
| Tool | Description |
|---|---|
get_account_dashboard_json | Get a comprehensive account dashboard with KPIs, trends, and top performers |
get_campaign_dashboard_json | Get a detailed dashboard for a specific campaign |
Example usage in Claude:
The account dashboard includes:
The campaign dashboard includes:
| Tool | Description |
|---|---|
get_performance_comparison_json | Compare metrics between multiple entities (campaigns, ad groups) |
Example usage in Claude:
The comparison visualizations include:
| Tool | Description |
|---|---|
get_performance_breakdown_json | Break down performance by various dimensions (device, geo, time, etc.) |
Example usage in Claude:
The breakdown visualizations include:
Example response for get_account_dashboard_json:
{ "date_range": "LAST 30 DAYS", "comparison_range": "PREVIOUS 30 DAYS", "visualization": { "charts": [ { "type": "line", "title": "Cost Trend", "data": { ... } }, { "type": "line", "title": "Engagement Trend", "data": { ... } }, { "type": "doughnut", "title": "Cost Distribution by Campaign", "data": { ... } } ], "tables": [ { "title": "Account Performance", "type": "kpi_cards", "cards": [ ... ] }, { "title": "Top Campaigns by Spend", "headers": ["Campaign", "Budget", "Status", "Cost"], "rows": [ ... ] } ] } }
The following MCP tools provide automated insights and recommendations based on account data analysis:
| Tool | Description |
|---|---|
get_performance_anomalies | Detect significant changes in performance metrics across campaigns, ad groups, or keywords |
get_performance_anomalies_json | Get performance anomaly data in JSON format with visualizations |
Example usage in Claude:
The performance anomaly detection includes:
| Tool | Description |
|---|---|
get_optimization_suggestions | Generate actionable optimization suggestions for an account |
get_optimization_suggestions_json | Get optimization suggestions in JSON format with visualizations |
Example usage in Claude:
The optimization suggestions include:
| Tool | Description |
|---|---|
get_opportunities | Discover growth opportunities in a Google Ads account |
get_opportunities_json | Get growth opportunities in JSON format with visualizations |
Example usage in Claude:
The opportunity discovery includes:
| Tool | Description |
|---|---|
get_account_insights_json | Get comprehensive account insights combining anomalies, suggestions, and opportunities |
Example usage in Claude:
The integrated insights dashboard includes:
Example response for get_performance_anomalies:
Google Ads Performance Anomalies
Account ID: 123-456-7890
Entity Type: CAMPAIGN
Date Range: 2025-05-15 to 2025-05-22
Comparison Period: PREVIOUS_PERIOD
Total Anomalies Detected: 3
Entity Name Metric Current Previous Change Severity
----------------------------------------------------------------------------------------------
Search - Brand Terms clicks 250 180 +38.9% MEDIUM
Display - Retargeting cost $452.18 $325.45 +38.9% MEDIUM
Shopping - Products impressions 5,420 8,750 -38.1% HIGH
Example response for get_optimization_suggestions:
Google Ads Optimization Suggestions
Account ID: 123-456-7890
Date Range: 2025-04-22 to 2025-05-22
Total Suggestions: 5
Budget Allocation Suggestions (2)
--------------------------------------------------
HIGH: Increase budget for campaign 'Search - Generic Terms' which is limited by budget (currently at 98% utilization)
Action: Consider increasing the budget by 10-20% to allow for growth
MEDIUM: Campaign 'Display - Awareness' is significantly under budget (only 45% utilized)
Action: Consider decreasing the budget to improve overall account efficiency, or reallocate to better-performing campaigns
Bid Management Suggestions (2)
--------------------------------------------------
HIGH: Keyword 'summer shoes sale' has strong conversion rate (8.5%) at $12.50 per conversion
Action: Increase bid by 10-15% to capture more traffic for this high-performing keyword
MEDIUM: Keyword 'generic footwear' has high CPC ($2.75) with no conversions after 45 clicks
Action: Decrease bid by 25-30% or pause if performance doesn't improve
Negative Keywords Suggestions (1)
--------------------------------------------------
MEDIUM: Add 'free shoes' as a negative keyword - spent $45.25 with no conversions
Action: Add 'free shoes' as a negative exact match keyword to prevent further wasted spend
Example response for get_opportunities:
Google Ads Growth Opportunities
Account ID: 123-456-7890
Date Range: 2025-04-22 to 2025-05-22
Total Opportunities: 4
Keyword Expansion Opportunities (2)
--------------------------------------------------
HIGH: Add 'summer sandals women' as a keyword in ad group 'Women's Footwear'
Action: Add 'summer sandals women' as an exact match keyword to better control bidding and relevance
MEDIUM: Add 'designer shoes discount' as a keyword in ad group 'Designer Collection'
Action: Add 'designer shoes discount' as an exact match keyword to better control bidding and relevance
Ad Variation Opportunities (2)
--------------------------------------------------
MEDIUM: Create additional ad variations for ad group 'Men's Dress Shoes'
Action: Add at least one more responsive search ad to test different headlines and descriptions
MEDIUM: Create additional ad variations for ad group 'Women's Athletic Shoes'
Action: Add at least one more responsive search ad to test different headlines and descriptions
This repository includes Kubernetes manifests for deployment:
kubernetes/dev/ - Development environment deploymentkubernetes/test/ - Test environment deploymentkubernetes/prod/ - Production environment deploymentCI/CD pipelines are configured using GitHub Actions for automated testing, building, and deployment.
Run the test suite:
pytest
Run specific tests:
# Test Ad Group functionality
python -m google_ads_mcp_server.tests.unit.test_ad_groups
# Test Keyword functionality
python -m google_ads_mcp_server.tests.unit.test_keywords
# Test Budget functionality
python -m google_ads_mcp_server.tests.unit.test_budgets
# Test MCP Tools
python -m google_ads_mcp_server.tests.unit.test_tools
# Test Visualization formatters
python -m google_ads_mcp_server.tests.unit.test_visualizations
# Test Budget Visualizations
python -m google_ads_mcp_server.tests.unit.test_budget_visualizations
git checkout -b feature/my-featuregit commit -am 'Add new feature'git push origin feature/my-featureThis project is licensed under the MIT License - see the LICENSE file for details.