Google Ads MCP Server

How to use

Set up and run the Google Ads MCP Server locally or in a container, then connect Claude Desktop to the MCP server to query data, visualize metrics, and run management actions. You can manage ad groups, keywords, and budgets, view dashboards, and receive automated insights that guide optimization.

How to install

# Prerequisites
- Python 3.9 or higher
- Claude Desktop
- Google Ads API credentials

# Local development
# 1) Clone the project
git clone https://github.com/yourusername/google-ads-mcp.git
cd google-ads-mcp

# 2) (Recommended) Create a Python virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3) Install dependencies
pip install -r requirements.txt

# 4) Create and configure environment variables
cp .env.example .env
# Edit .env with your Google Ads credentials

# 5) Start the MCP server
python server.py
```

```bash
# Docker deployment
# 1) Build the Docker image
docker build -t google-ads-mcp:latest .

# 2) Run the container with environment variables
docker run -p 8000:8000 --env-file .env google-ads-mcp:latest

# Optional: use docker-compose if provided
docker-compose up -d

Configuration

The server supports multiple environments and environment-specific configurations. You set the runtime environment with APP_ENV as dev, test, or prod, and you configure other settings via environment variables. Feature flags let you enable or disable specific functionality. Ensure your Google Ads credentials are provided in a way that the MCP server can access them at startup.

Security

Credentials are kept separate from code and loaded via environment variables or Kubernetes secrets in production. The MCP server includes authentication for API access and rate limiting in production environments. Follow best practices to keep credentials secure and rotate keys regularly.

Environment variables (example)

# Example environment variables (placeholders; replace with actual values)
GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN
GOOGLE_ADS_CLIENT_ID=YOUR_CLIENT_ID
GOOGLE_ADS_CLIENT_SECRET=YOUR_CLIENT_SECRET
GOOGLE_ADS_REFRESH_TOKEN=YOUR_REFRESH_TOKEN
APP_ENV=dev

Claude Desktop integration

Configure Claude Desktop to connect to the MCP server by adding a tooling entry that points to the Python runtime and the server script. After saving, restart Claude Desktop and use the tools to query Google Ads data and create visualizations.

{"mcpServers": {
  "google_ads": {
    "command": "python",
    "args": ["server.py"]
  }
}}

Examples of what you can do

Ask Claude to show account performance, compare campaigns, visualize budget distribution, or list ad groups and keywords. Use natural language prompts that map to the provided tools for ad group management, keyword management, budget management, and the enhanced visualization and insights capabilities.

Ad Group Management Tools

You can manage ad groups with the following tools. Each tool retrieves or updates data for your Google Ads accounts.

Keyword Management Tools

Handle keywords with dedicated tools to fetch, visualize, add, update, or remove keywords, and to analyze search terms for insights.

Budget Management Tools

Manage campaign budgets, analyze utilization, and obtain recommendations to optimize spending across campaigns.

Enhanced Visualization Tools

Access dashboards and visualizations to compare performance, breakdown metrics by device or geography, and understand budget and performance trends.

Automated Insights Tools

Gain anomaly detection, optimization suggestions, opportunities, and an integrated insights dashboard to guide improvements.

Testing

Run the test suite with pytest to validate functionality across ad group, keyword, budget features, tools, visualizations, and budget visualizations.

get_ad_groups

Retrieve ad groups for a Google Ads account with optional filtering and visualization support.

get_ad_groups_json

Fetch ad groups data in JSON format suitable for visualizations.

get_ad_group_performance

Get performance metrics for a specific ad group.

get_ad_group_performance_json

Return ad group performance metrics in JSON format for visualization.

create_ad_group

Create a new ad group within a campaign.

update_ad_group

Update attributes of an existing ad group.

get_keywords

Retrieve keywords for a Google Ads account with optional filtering.

get_keywords_json

Fetch keywords in JSON format for visualization.

add_keywords

Add new keywords to an ad group.

update_keyword

Update an existing keyword 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

Analyze search terms performance and extract insights.

analyze_search_terms_json

Get insights about search terms performance in JSON format.

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).

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.

get_performance_comparison_json

Compare metrics between multiple entities (campaigns, ad groups).

get_performance_breakdown_json

Break down performance by dimensions like device, geo, or time.

get_performance_anomalies

Detect significant changes in performance across campaigns, ad groups, or keywords.

get_performance_anomalies_json

Provide anomaly data in JSON format with visualizations.

get_optimization_suggestions

Generate actionable optimization suggestions for the account.

get_optimization_suggestions_json

Get optimization suggestions in JSON format with visualizations.

get_opportunities

Discover growth opportunities in the Google Ads account.

get_opportunities_json

Get growth opportunities in JSON format with visualizations.

get_account_insights_json

Get a comprehensive insights dashboard combining anomalies, suggestions, and opportunities.