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

Via PyPI (recommended)

uvx bluealpha-google-ads-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bluealpha-google-ads": {
      "command": "uvx",
      "args": ["bluealpha-google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CLIENT_ID": "your-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your-mcc-id"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add bluealpha-google-ads -- uvx bluealpha-google-ads-mcp

From source

cd servers/google-ads
uv sync
cp .env.example .env
# Edit .env with your Google Ads API credentials
uv run bluealpha-google-ads-mcp

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)

Metadata

Release files for bluealpha-google-ads-mcp 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bluealpha-google-ads-mcp 0.2.4
File	Size	Uploaded
bluealpha_google_ads_mcp-0.2.4.tar.gz	199.0 kB	Apr 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for bluealpha-google-ads-mcp 0.2.4
File	Interpreter	ABI	Platform	Reset
bluealpha_google_ads_mcp-0.2.4-py3-none-any.whl 90.1 kB Apr 4, 2026	Python 3	none	any	Details

Total release size: 289.1 kB

Release files / bluealpha_google_ads_mcp-0.2.4.tar.gz

Download URL	bluealpha_google_ads_mcp-0.2.4.tar.gz
Size	199.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`489611438b300630a6edca9c4a1c1448a7d42c8bc0671fc71b110088ce029053`
BLAKE2b-256 checksum How to use checksums	`9e9619008b6364f775dcb7c30084ecb7644586e2a8ef48b6ac4e570bfd3b4e18`
Upload date	Apr 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.11`

Release files / bluealpha_google_ads_mcp-0.2.4-py3-none-any.whl

Download URL	bluealpha_google_ads_mcp-0.2.4-py3-none-any.whl
Size	90.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`363dd9bf30b48e95e4b4e8c14174dc746272e289fd001db51afc1d3720a19291`
BLAKE2b-256 checksum How to use checksums	`e6f03eed19c8ce0ed8890616deb483082d2d7ce34286685213868f39510e68c6`
Upload date	Apr 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.11`