MatiousCorp/google-ad-manager-mcp

PyPI version License: MIT Python 3.10+ MCP

Automate Google Ad Manager with AI. An MCP server that lets AI assistants like Claude, ChatGPT, Gemini, Cursor, and VS Code manage your ad campaigns, line items, creatives, and more through natural language.

Built by Matious — We build custom AI tools and MCP servers for businesses.

---

Why This Exists

Managing Google Ad Manager is tedious. Creating campaigns, uploading creatives, and configuring line items involves countless clicks through a complex UI.

This MCP server changes that. Connect it to Claude and manage your entire ad operations through conversation:

• "Create a new campaign for Nike ending December 31st"
• "Upload all creatives from this folder and associate them with the Display line item"
• "Check which orders are currently delivering"

No more clicking. Just tell Claude what you need.

Features

• Order Management: List, create, and manage orders
• Line Item Management: Create, duplicate, and configure line items
• Creative Management: Upload images, associate with line items, bulk upload
• Advertiser Management: Find, create, and list advertisers
• Verification Tools: Verify line item setup, check delivery status
• Campaign Workflow: Complete campaign creation in one operation

Installation

From PyPI (Recommended)

pip install google-ad-manager-mcp

Or with uv:

uv pip install google-ad-manager-mcp

From Source

git clone https://github.com/MatiousCorp/google-ad-manager-mcp.git
cd google-ad-manager-mcp
pip install -e .

Dependencies

• FastMCP: MCP server framework with native middleware support
• googleads: Google Ad Manager SOAP API client

Configuration

The server uses environment variables for configuration:

Variable	Description	Required
GAM_CREDENTIALS_PATH	Path to service account JSON	Yes
GAM_NETWORK_CODES	Comma-separated list of GAM network codes (first is the default)	Yes
GAM_MCP_TRANSPORT	Transport mode: stdio or http	No (default: stdio)
GAM_MCP_HOST	Server host (HTTP mode only)	No (default: 0.0.0.0)
GAM_MCP_PORT	Server port (HTTP mode only)	No (default: 8000)
GAM_MCP_AUTH_TOKEN	Authentication token (HTTP mode only)	No (auto-generated if not set)

Multi-Network Support

You can manage multiple GAM networks with a single server instance. List all network codes in GAM_NETWORK_CODES — the first one is the default:

export GAM_NETWORK_CODES="31083078,22706375620,98765432"

All tools accept an optional network_code parameter. When omitted, the first (default) network is used. The same service account credentials are shared across all networks — just ensure the service account email has been added as a user in each network.

For Claude Code MCP configuration:

{
  "google-ad-manager": {
    "command": "uvx",
    "args": ["google-ad-manager-mcp"],
    "env": {
      "GAM_CREDENTIALS_PATH": "/path/to/credentials.json",
      "GAM_NETWORK_CODES": "31083078,22706375620"
    }
  }
}

Authentication

The server implements Bearer token authentication using FastMCP native middleware, following MCP security best practices.

Security Features

• FastMCP Native Middleware: Uses FastMCP 2.x middleware for proper MCP lifecycle management
• Cryptographically secure tokens: Generated using secrets.token_hex(32)
• Timing attack prevention: Uses constant-time comparison (hmac.compare_digest)
• Tool-level authentication: Auth validated on every tool call
• Audit logging: All authentication failures logged

How It Works

Authentication is enforced at the tool level using FastMCP's middleware system:

• When a tool is called, the middleware validates the Authorization header
• If no token is configured (GAM_MCP_AUTH_TOKEN not set), requests are allowed
• Invalid or missing tokens return a ToolError with a helpful message

Setup

For remote deployments, set a fixed authentication token:

# Generate a secure token
python -c "import secrets; print(secrets.token_hex(32))"

# Set it as environment variable
export GAM_MCP_AUTH_TOKEN="your-generated-token"

If not set, a random token is generated at startup and displayed in the logs.

Clients must include the token in the Authorization header:

Authorization: Bearer your-generated-token

Endpoints

Endpoint	Description
/mcp	MCP protocol endpoint (auth validated on tool calls)

Running the Server

Local Development

# Using the installed command
gam-mcp

# Or directly with Python
python -m gam_mcp.server

# With custom configuration
GAM_NETWORK_CODE=12345678 GAM_MCP_PORT=9000 gam-mcp

Docker Deployment

The Docker image runs as a non-root user (appuser) for security.

Build the Image

docker build -t google-ad-manager-mcp .

Run the Container

# Basic usage with credentials mounted
docker run -d \
  --name gam-mcp \
  -p 8000:8000 \
  -v /path/to/your/credentials.json:/app/credentials.json:ro \
  -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \
  google-ad-manager-mcp

# With authentication token (recommended for production)
docker run -d \
  --name gam-mcp \
  -p 8000:8000 \
  -v /path/to/your/credentials.json:/app/credentials.json:ro \
  -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \
  -e GAM_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))") \
  google-ad-manager-mcp

# With custom port
docker run -d \
  --name gam-mcp \
  -p 9000:8000 \
  -v /path/to/your/credentials.json:/app/credentials.json:ro \
  -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \
  -e GAM_MCP_PORT=8000 \
  google-ad-manager-mcp

View Logs

# View startup logs (includes generated auth token if not set)
docker logs gam-mcp

# Follow logs
docker logs -f gam-mcp

Docker Compose

Create a docker-compose.yml file:

version: '3.8'
services:
  gam-mcp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./credentials.json:/app/credentials.json:ro
    environment:
      - GAM_NETWORK_CODE=YOUR_NETWORK_CODE
      - GAM_MCP_AUTH_TOKEN=your-secure-token
    restart: unless-stopped

Run with:

docker-compose up -d

Verify the Container

# Check container is running
docker ps

# Test the endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}'

Cloud Deployment (Railway, Fly.io, etc.)

1. Set environment variables in your cloud provider:

   • GAM_CREDENTIALS_PATH: Path to credentials (or use secrets)
   • GAM_NETWORK_CODE: Your Ad Manager network code
   • GAM_MCP_AUTH_TOKEN: A secure authentication token

2. Deploy using the included Dockerfile

Connecting to AI Assistants

Claude Desktop (uvx - Recommended)

The easiest way to use this server with Claude Desktop. Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-ad-manager": {
      "command": "uvx",
      "args": ["google-ad-manager-mcp"],
      "env": {
        "GAM_CREDENTIALS_PATH": "/path/to/your/credentials.json",
        "GAM_NETWORK_CODE": "YOUR_NETWORK_CODE"
      }
    }
  }
}

Claude Desktop (Docker)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-ad-manager": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GAM_NETWORK_CODE",
        "-v", "/path/to/credentials.json:/app/credentials.json:ro",
        "google-ad-manager-mcp"
      ],
      "env": {
        "GAM_NETWORK_CODE": "YOUR_NETWORK_CODE"
      }
    }
  }
}

Claude Desktop (HTTP Mode)

If running the server in HTTP mode:

{
  "mcpServers": {
    "google-ad-manager": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Remote Server with Authentication

If deploying remotely with authentication enabled:

{
  "mcpServers": {
    "google-ad-manager": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-token"
      }
    }
  }
}

Other MCP Clients

This server works with any MCP-compatible client, including:

• ChatGPT Desktop - OpenAI adopted MCP in March 2025
• Cursor - AI-powered IDE with MCP support
• VS Code - Via MCP extensions
• Windsurf, Zed, Codeium - Various IDE integrations

Refer to each client's documentation for MCP server configuration.

Testing with MCP Inspector

# Without authentication
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

# With authentication (set header in Inspector UI)
# Header: Authorization
# Value: Bearer your-token

Available Tools

Order Tools

Tool	Description
list_delivering_orders	List all orders with delivering line items
get_order	Get order details by ID or name
create_order	Create a new order
find_or_create_order	Find existing or create new order

Line Item Tools

Tool	Description
get_line_item	Get line item details
create_line_item	Create a new line item
duplicate_line_item	Duplicate an existing line item
update_line_item	Update line item properties (name, type, delivery rate, priority, cost, goal, end date)
list_line_items_by_order	List all line items for an order
pause_line_item	Pause a delivering line item
resume_line_item	Resume a paused line item
archive_line_item	Archive a line item
approve_line_item	Approve a line item (for approval workflows)

Creative Tools

Tool	Description
upload_creative	Upload an image creative
associate_creative_with_line_item	Associate creative with line item
upload_and_associate_creative	Upload and associate in one step
bulk_upload_creatives	Upload all creatives from a folder
get_creative	Get creative details
list_creatives_by_advertiser	List creatives for an advertiser
update_creative	Update creative destination URL or name
list_creatives_by_line_item	List creatives associated with a line item
create_third_party_creative	Create HTML/JavaScript ad tag (DCM, custom HTML)
get_creative_preview_url	Generate preview URL to see creative on your site

Advertiser Tools

Tool	Description
find_advertiser	Find advertiser by name
get_advertiser	Get advertiser details
list_advertisers	List all advertisers
create_advertiser	Create a new advertiser
find_or_create_advertiser	Find or create advertiser

Verification Tools

Tool	Description
verify_line_item_setup	Verify line item configuration
check_line_item_delivery_status	Check delivery progress
verify_order_setup	Verify entire order setup

Reporting Tools

Tool	Description
run_delivery_report	Generate delivery report (impressions, clicks, CTR, revenue)
run_inventory_report	Generate inventory report (ad requests, fill rate)
run_custom_report	Generate custom report with specified dimensions and metrics

Workflow Tools

Tool	Description
create_campaign	Complete campaign creation workflow

Example Usage with Claude

User: List all delivering orders

Claude: [Uses list_delivering_orders tool]
Here are the currently delivering orders:
1. Campaign IPhone 17 Pro 2025/2026 (ID: 123456)
   - Display line item: 45,000 impressions delivered

User: Create a new campaign for "ACME Corp" ending December 31, 2025

Claude: [Uses create_campaign tool]
I'll create the campaign with:
- Advertiser: ACME Corp
- Order: ACME Campaign 2025
- Line Item: Display
- End Date: December 31, 2025

Campaign created successfully!
- Order ID: 789012
- Line Item ID: 345678
- 4 creatives uploaded and associated

Development

Setup

# Clone the repository
git clone https://github.com/MatiousCorp/google-ad-manager-mcp.git
cd google-ad-manager-mcp

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=gam_mcp --cov-report=html

# Run specific test file
pytest tests/test_utils.py

Code Quality

# Run linter
ruff check .

# Run linter with auto-fix
ruff check . --fix

Roadmap

The following features are planned for future releases:

Near-term

• Ad Unit Management - List, get, and create ad units with hierarchy support
• Placement Management - Manage inventory placements and targeting
• Forecast & Availability - Check inventory availability and forecast impressions
• Creative Preview Links - Generate preview URLs for creative-line item combinations

Medium-term

• Advanced Targeting - Geographic, device, daypart, and custom key-value targeting
• Reporting Tools - Generate and retrieve performance reports
• Bulk Operations - Batch updates for line items, creatives, and targeting
• HTML5/Video Creatives - Support for rich media and video creative uploads

Long-term

• Audience Management - Create and manage audience segments
• User & Permissions - Manage users, roles, and order assignments
• Yield Management - Configure yield groups and optimization
• Custom Reporting - Scheduled reports with export capabilities

Community Requests

Have a feature request? Open an issue to suggest new functionality.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

API Version

Uses Google Ad Manager SOAP API version v202502.

License

MIT - see LICENSE for details.

---

Need a Custom MCP Server?

This project is built and maintained by Matious.

We specialize in building custom AI tools and MCP servers that integrate with your existing systems. Whether you need to connect Claude to your CRM, ERP, ad platforms, or internal tools — we can help.

What we build:

• Custom MCP servers for any API or platform
• AI-powered automation workflows
• Claude integrations for business operations

Get in touch: matious.com