Skip to content
/ google-ad-manager-mcp Public

MCP server for Google Ad Manager. Manage ad campaigns, orders, line items, and creatives through AI assistants like Claude, ChatGPT, Gemini, Cursor, and VS Code. Automate your ad operations with natural language instead of clicking through the GAM UI. Built by Matious.

License

MIT license
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

MatiousCorp/google-ad-manager-mcp

BranchesTags

Repository files navigation

Google Ad Manager MCP Server

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_CODE Ad Manager network code 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)

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_name Rename a line item
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 v202411.

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

About

MCP server for Google Ad Manager. Manage ad campaigns, orders, line items, and creatives through AI assistants like Claude, ChatGPT, Gemini, Cursor, and VS Code. Automate your ad operations with natural language instead of clicking through the GAM UI. Built by Matious.

Topics

python automation mcp gemini openai gam advertising ad-tech claude google-ad-manager ai-tools chatgpt anthropic model-context-protocol

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages