Metadata-Version: 2.4
Name: bluealpha-google-ads-mcp
Version: 0.2.4
Summary: MCP server for Google Ads API
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.12.13
Requires-Dist: fastmcp>=2.9.0
Requires-Dist: google-ads>=30.0.0
Requires-Dist: google-auth>=2.40.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.32.4
Provides-Extra: dev
Requires-Dist: pyright>=1.1.402; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest>=8.4.1; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-protobuf>=5.29.0.20241127; extra == 'dev'
Description-Content-Type: text/markdown

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

```bash
uvx bluealpha-google-ads-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

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

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

### From source

```bash
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

```bash
# 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) |
