bluealpha-google-ads-mcp 0.1.0

MCP server for Google Ads API

Google Ads MCP Server

A Model Context Protocol (MCP) server for Google Ads, built on the official Python SDK (v23+) with FastMCP.

Overview

32 focused tools for LLM interaction with Google Ads accounts. Uses GAQL (Google Ads Query Language) as the universal read mechanism, dedicated tools for write operations, and 7 workflow analysis tools for campaign intelligence.

Architecture

Server	Tools	Purpose
Read	8	GAQL execution, account discovery, keyword ideas, geo targets, field metadata, recommendations
Write	16	Campaign/budget/ad group/ad/keyword CRUD, targeting, recommendations
Workflow	7	Campaign audit, underspend diagnosis, budget reallocation, creative analysis, fatigue detection, audience analysis, test monitoring
Utility	1	Connection status check

Tools

Read Tools (8)

Tool	Description
execute_query	Run any GAQL query with pagination
execute_query_stream	Stream large GAQL result sets
list_accessible_customers	Discover accounts (no customer ID needed)
generate_keyword_ideas	Search volume, competition, bid estimates
suggest_geo_targets	Location name to geo target ID resolution
get_field_metadata	Field schema for building GAQL queries
validate_query_fields	Check field compatibility before querying
get_recommendations	Google's optimization suggestions

Write Tools (16)

Tool	Description
create_campaign / update_campaign	Campaign CRUD
create_campaign_budget / update_campaign_budget	Budget management
create_ad_group / update_ad_group	Ad group CRUD
create_ad / update_ad_status	Ad creation and status changes
add_keywords / remove_keyword	Keyword management
add_negative_keywords	Campaign-level negative keywords
add_location_targeting / add_language_targeting	Geo and language targeting
remove_campaign_criterion	Remove targeting criteria
apply_recommendation / dismiss_recommendation	Act on Google's suggestions

Workflow Tools (7)

Tool	Description
audit_campaign_structure	Campaign scoring (0-110) across 6 dimensions
diagnose_underspend	5-layer underspend diagnostic
analyze_budget_reallocation	Efficiency scoring + constraint checks
analyze_creatives	Creative scoring (efficiency, quality, engagement)
detect_creative_fatigue	Week-over-week trigger comparison
analyze_audiences	Audience efficiency scoring and classification
monitor_incrementality_test	Test integrity monitoring with alert tiers

Installation

# Install dependencies
uv sync

# Set up credentials (see .env.example)
cp .env.example .env
# Edit .env with your Google Ads API credentials

Usage

# Run the server
uv run main.py

# Or use the convenience script
./run.sh

MCP Client Configuration

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/path/to/servers/google-ads"
    }
  }
}

Development

# Format
uv run ruff format .

# Lint + type check
uv run ruff check --fix .
uv run pyright

# Run tests
uv run pytest tests/ -v

Credentials

Required environment variables (see .env.example):

Variable	Required	Description
GOOGLE_ADS_DEVELOPER_TOKEN	Yes	API developer token
GOOGLE_ADS_CLIENT_ID	Yes	OAuth client ID
GOOGLE_ADS_CLIENT_SECRET	Yes	OAuth client secret
GOOGLE_ADS_REFRESH_TOKEN	Yes	OAuth refresh token
GOOGLE_ADS_LOGIN_CUSTOMER_ID	No	MCC account ID (for managing multiple accounts)