Google Ad Manager

Google Ad Manager MCP Server

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.

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:

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

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

Line Item Tools

Creative Tools

Advertiser Tools

Verification Tools

…