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.
- Access Google Ads campaigns, accounts, and performance metrics via Claude
- Budget Management API Endpoints with visualizations (Project Quantum Pulse Phase 3)
- Keyword Management API Endpoints with visualizations (Project Quantum Pulse Phase 2)
- Ad Group Management API Endpoints (Project Quantum Pulse Phase 1)
- Support for both Manager (MCC) and client account data
- Built-in caching to improve performance and reduce API calls
- Claude Artifacts integration for data visualization
- Multi-environment support (development, testing, production)
- Containerized deployment with Docker
This repository implements the Project Quantum Pulse roadmap for enhanced Google Ads management capabilities:
- Get ad groups with filtering capabilities
- View ad group performance metrics
- Create new ad groups
- Update existing ad groups
- Visualize ad group performance
- Browse keywords with filtering capabilities âś…
- Analyze search terms and find insights âś…
- Add, update, and remove keywords âś…
- Visualize keyword performance with tables, charts, and word clouds âś…
- Retrieve campaign budgets with performance metrics âś…
- Analyze budget utilization and distribution âś…
- Generate budget recommendations âś…
- Visualize budget performance with charts and tables âś…
- Update budget properties (API call implementation pending)
- Implement comprehensive dashboard templates âś…
- Create comparison visualization templates âś…
- Build breakdown visualization templates âś…
- Integration, testing, and documentation âś…
- Implement performance anomaly detection âś…
- Generate optimization suggestions âś…
- Discover growth opportunities âś…
- Create integrated insights dashboard âś…
- Python 3.9 or higher
- Google Ads API credentials
- Claude Desktop
-
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
.envfile 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:
- Set
APP_ENVtodev,test, orprodto specify the environment - Configure environment variables as documented in
.env.example - Feature flags allow enabling/disabling specific functionality
-
Configure 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:
- "Show me my Google Ads account performance"
- "What campaigns are performing well in my account?"
- "Create a visualization of my campaign performance"
- "List all ad groups in my 123-456-7890 account"
- "Update the status of ad group 12345678 to PAUSED"
- "Create a new ad group called 'Summer Products 2025' in campaign 98765432"
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:
- "List all keywords in my 123-456-7890 account"
- "Show me search terms for campaign 12345678"
- "Add a broad match keyword 'summer shoes' to ad group 87654321"
- "Pause keyword 12345"
- "Analyze search terms in my account to find opportunities"
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:
- "Show me all campaign budgets in my account"
- "Analyze budget utilization across my campaigns"
- "Visualize budget distribution by campaign"
- "Which budgets are being depleted too quickly?"
- "What are the budget recommendations for my account?"
- "Update the daily budget for campaign 12345678 to $100"
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:
- "Show me an account dashboard for the last 30 days"
- "Create a dashboard for campaign 12345678"
- "Compare my account performance to the previous month"
- "Show a dashboard with all my campaign KPIs"
The account dashboard includes:
- KPI cards with period-over-period comparisons
- Performance trend charts for key metrics
- Top campaigns and ad groups by performance
- Cost distribution visualizations
The campaign dashboard includes:
- Campaign overview and details
- KPI cards with period-over-period comparisons
- Performance trend charts
- Ad group breakdown
- Device performance distribution
- Top keywords
| Tool | Description |
|---|---|
get_performance_comparison_json |
Compare metrics between multiple entities (campaigns, ad groups) |
Example usage in Claude:
- "Compare campaigns 123456 and 789012"
- "Show me a side-by-side comparison of my top 3 campaigns"
- "Compare clicks and conversions across my search campaigns"
- "Which campaign has better performance, 123456 or 789012?"
The comparison visualizations include:
- Side-by-side bar charts for key metrics
- Detailed comparison tables with absolute and relative differences
- Radar charts for multi-metric comparisons (when 3+ metrics are selected)
| Tool | Description |
|---|---|
get_performance_breakdown_json |
Break down performance by various dimensions (device, geo, time, etc.) |
Example usage in Claude:
- "Break down campaign 123456 performance by device"
- "Show my account performance by day of week"
- "What's the geographic distribution of my ad spend?"
- "Break down campaign 123456 by device and time"
The breakdown visualizations include:
- Stacked bar charts for categorical dimensions (device, network, geo)
- Line charts for time dimensions (day, week, month)
- Treemap charts for hierarchical data visualization
- Detailed tables with segment metrics and percentage contribution
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:
- "Find performance anomalies in my account for the last 7 days"
- "Detect unusual changes in my campaign performance"
- "Which metrics have significant changes compared to last week?"
- "Analyze my account for performance issues"
The performance anomaly detection includes:
- Statistical analysis to identify outliers in key metrics
- Comparison against previous periods
- Severity scoring for detected anomalies
- Visualization of anomalies by metric and entity
- Ranked list of most significant changes
| 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:
- "What optimizations should I make to my account?"
- "Suggest ways to improve my campaign performance"
- "Give me optimization ideas for my keywords"
- "How can I better allocate my budget?"
The optimization suggestions include:
- Bid management recommendations (increase/decrease bids)
- Budget allocation recommendations
- Negative keyword suggestions
- Ad copy improvement recommendations
- Account structure suggestions
| 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:
- "Find growth opportunities in my account"
- "What search terms should I add as keywords?"
- "Where can I expand my advertising reach?"
- "Discover new keyword opportunities based on search terms"
The opportunity discovery includes:
- Keyword expansion suggestions based on high-performing search terms
- Ad variation recommendations for top ad groups
- Account structure optimization opportunities
- Prioritized list of actions by potential impact
| Tool | Description |
|---|---|
get_account_insights_json |
Get comprehensive account insights combining anomalies, suggestions, and opportunities |
Example usage in Claude:
- "Give me a complete analysis of my account"
- "What's the overall health of my Google Ads campaigns?"
- "Show me everything I should know about my account"
- "Generate a comprehensive insights report"
The integrated insights dashboard includes:
- Summary statistics and key findings
- Tabs for anomalies, suggestions, and opportunities
- Prioritized recommendations
- Interactive visualizations for each insight type
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 deployment
CI/CD pipelines are configured using GitHub Actions for automated testing, building, and deployment.
- All credentials are stored in Kubernetes secrets or environment variables, never in code
- The server uses proper authentication for API access
- Rate limiting is enabled in production environments
- Container security best practices are followed
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
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Commit your changes:
git commit -am 'Add new feature' - Push to the branch:
git push origin feature/my-feature - Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- Google Ads API team for their documentation and support
- Anthropic for Claude and the Model Context Protocol