Built by Matious — We build custom AI tools and MCP servers for businesses. 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" - "
Add this skill
npx mdskills install MatiousCorp/google-ad-manager-mcpComprehensive MCP server with extensive Google Ad Manager tools, excellent docs, and proper auth implementation
1# Google Ad Manager MCP Server23[](https://pypi.org/project/google-ad-manager-mcp/)4[](https://opensource.org/licenses/MIT)5[](https://www.python.org/downloads/)6[](https://modelcontextprotocol.io/)78> **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.910<p align="center">11 <strong>Built by <a href="https://matious.com">Matious</a></strong> — We build custom AI tools and MCP servers for businesses.12</p>1314---1516## Why This Exists1718Managing Google Ad Manager is tedious. Creating campaigns, uploading creatives, and configuring line items involves countless clicks through a complex UI.1920**This MCP server changes that.** Connect it to Claude and manage your entire ad operations through conversation:2122- *"Create a new campaign for Nike ending December 31st"*23- *"Upload all creatives from this folder and associate them with the Display line item"*24- *"Check which orders are currently delivering"*2526No more clicking. Just tell Claude what you need.2728## Features2930- **Order Management**: List, create, and manage orders31- **Line Item Management**: Create, duplicate, and configure line items32- **Creative Management**: Upload images, associate with line items, bulk upload33- **Advertiser Management**: Find, create, and list advertisers34- **Verification Tools**: Verify line item setup, check delivery status35- **Campaign Workflow**: Complete campaign creation in one operation3637## Installation3839### From PyPI (Recommended)4041```bash42pip install google-ad-manager-mcp43```4445Or with uv:4647```bash48uv pip install google-ad-manager-mcp49```5051### From Source5253```bash54git clone https://github.com/MatiousCorp/google-ad-manager-mcp.git55cd google-ad-manager-mcp56pip install -e .57```5859### Dependencies6061- **[FastMCP](https://github.com/jlowin/fastmcp)**: MCP server framework with native middleware support62- **[googleads](https://github.com/googleads/googleads-python-lib)**: Google Ad Manager SOAP API client6364## Configuration6566The server uses environment variables for configuration:6768| Variable | Description | Required |69|----------|-------------|----------|70| `GAM_CREDENTIALS_PATH` | Path to service account JSON | **Yes** |71| `GAM_NETWORK_CODE` | Ad Manager network code | **Yes** |72| `GAM_MCP_TRANSPORT` | Transport mode: `stdio` or `http` | No (default: `stdio`) |73| `GAM_MCP_HOST` | Server host (HTTP mode only) | No (default: `0.0.0.0`) |74| `GAM_MCP_PORT` | Server port (HTTP mode only) | No (default: `8000`) |75| `GAM_MCP_AUTH_TOKEN` | Authentication token (HTTP mode only) | No (auto-generated if not set) |7677## Authentication7879The server implements Bearer token authentication using [FastMCP native middleware](https://gofastmcp.com/python-sdk/fastmcp-server-auth-auth), following [MCP security best practices](https://modelcontextprotocol.io/specification/draft/basic/security_best_practices).8081### Security Features8283- **FastMCP Native Middleware**: Uses FastMCP 2.x middleware for proper MCP lifecycle management84- **Cryptographically secure tokens**: Generated using `secrets.token_hex(32)`85- **Timing attack prevention**: Uses constant-time comparison (`hmac.compare_digest`)86- **Tool-level authentication**: Auth validated on every tool call87- **Audit logging**: All authentication failures logged8889### How It Works9091Authentication is enforced at the tool level using FastMCP's middleware system:92- When a tool is called, the middleware validates the `Authorization` header93- If no token is configured (`GAM_MCP_AUTH_TOKEN` not set), requests are allowed94- Invalid or missing tokens return a `ToolError` with a helpful message9596### Setup9798For remote deployments, set a fixed authentication token:99100```bash101# Generate a secure token102python -c "import secrets; print(secrets.token_hex(32))"103104# Set it as environment variable105export GAM_MCP_AUTH_TOKEN="your-generated-token"106```107108If not set, a random token is generated at startup and displayed in the logs.109110Clients must include the token in the Authorization header:111```112Authorization: Bearer your-generated-token113```114115### Endpoints116117| Endpoint | Description |118|----------|-------------|119| `/mcp` | MCP protocol endpoint (auth validated on tool calls) |120121## Running the Server122123### Local Development124125```bash126# Using the installed command127gam-mcp128129# Or directly with Python130python -m gam_mcp.server131132# With custom configuration133GAM_NETWORK_CODE=12345678 GAM_MCP_PORT=9000 gam-mcp134```135136### Docker Deployment137138The Docker image runs as a non-root user (`appuser`) for security.139140#### Build the Image141142```bash143docker build -t google-ad-manager-mcp .144```145146#### Run the Container147148```bash149# Basic usage with credentials mounted150docker run -d \151 --name gam-mcp \152 -p 8000:8000 \153 -v /path/to/your/credentials.json:/app/credentials.json:ro \154 -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \155 google-ad-manager-mcp156157# With authentication token (recommended for production)158docker run -d \159 --name gam-mcp \160 -p 8000:8000 \161 -v /path/to/your/credentials.json:/app/credentials.json:ro \162 -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \163 -e GAM_MCP_AUTH_TOKEN=$(python -c "import secrets; print(secrets.token_hex(32))") \164 google-ad-manager-mcp165166# With custom port167docker run -d \168 --name gam-mcp \169 -p 9000:8000 \170 -v /path/to/your/credentials.json:/app/credentials.json:ro \171 -e GAM_NETWORK_CODE=YOUR_NETWORK_CODE \172 -e GAM_MCP_PORT=8000 \173 google-ad-manager-mcp174```175176#### View Logs177178```bash179# View startup logs (includes generated auth token if not set)180docker logs gam-mcp181182# Follow logs183docker logs -f gam-mcp184```185186#### Docker Compose187188Create a `docker-compose.yml` file:189190```yaml191version: '3.8'192services:193 gam-mcp:194 build: .195 ports:196 - "8000:8000"197 volumes:198 - ./credentials.json:/app/credentials.json:ro199 environment:200 - GAM_NETWORK_CODE=YOUR_NETWORK_CODE201 - GAM_MCP_AUTH_TOKEN=your-secure-token202 restart: unless-stopped203```204205Run with:206```bash207docker-compose up -d208```209210#### Verify the Container211212```bash213# Check container is running214docker ps215216# Test the endpoint217curl -X POST http://localhost:8000/mcp \218 -H "Content-Type: application/json" \219 -H "Accept: application/json, text/event-stream" \220 -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}'221```222223### Cloud Deployment (Railway, Fly.io, etc.)2242251. Set environment variables in your cloud provider:226 - `GAM_CREDENTIALS_PATH`: Path to credentials (or use secrets)227 - `GAM_NETWORK_CODE`: Your Ad Manager network code228 - `GAM_MCP_AUTH_TOKEN`: A secure authentication token2292302. Deploy using the included Dockerfile231232## Connecting to AI Assistants233234### Claude Desktop (uvx - Recommended)235236The easiest way to use this server with Claude Desktop. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:237238```json239{240 "mcpServers": {241 "google-ad-manager": {242 "command": "uvx",243 "args": ["google-ad-manager-mcp"],244 "env": {245 "GAM_CREDENTIALS_PATH": "/path/to/your/credentials.json",246 "GAM_NETWORK_CODE": "YOUR_NETWORK_CODE"247 }248 }249 }250}251```252253### Claude Desktop (Docker)254255Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:256257```json258{259 "mcpServers": {260 "google-ad-manager": {261 "command": "docker",262 "args": [263 "run", "-i", "--rm",264 "-e", "GAM_NETWORK_CODE",265 "-v", "/path/to/credentials.json:/app/credentials.json:ro",266 "google-ad-manager-mcp"267 ],268 "env": {269 "GAM_NETWORK_CODE": "YOUR_NETWORK_CODE"270 }271 }272 }273}274```275276### Claude Desktop (HTTP Mode)277278If running the server in HTTP mode:279280```json281{282 "mcpServers": {283 "google-ad-manager": {284 "url": "http://localhost:8000/mcp"285 }286 }287}288```289290### Remote Server with Authentication291292If deploying remotely with authentication enabled:293294```json295{296 "mcpServers": {297 "google-ad-manager": {298 "url": "https://your-server.com/mcp",299 "headers": {300 "Authorization": "Bearer your-secure-token"301 }302 }303 }304}305```306307### Other MCP Clients308309This server works with any MCP-compatible client, including:310311- **ChatGPT Desktop** - OpenAI adopted MCP in March 2025312- **Cursor** - AI-powered IDE with MCP support313- **VS Code** - Via MCP extensions314- **Windsurf, Zed, Codeium** - Various IDE integrations315316Refer to each client's documentation for MCP server configuration.317318### Testing with MCP Inspector319320```bash321# Without authentication322npx @modelcontextprotocol/inspector http://localhost:8000/mcp323324# With authentication (set header in Inspector UI)325# Header: Authorization326# Value: Bearer your-token327```328329## Available Tools330331### Order Tools332333| Tool | Description |334|------|-------------|335| `list_delivering_orders` | List all orders with delivering line items |336| `get_order` | Get order details by ID or name |337| `create_order` | Create a new order |338| `find_or_create_order` | Find existing or create new order |339340### Line Item Tools341342| Tool | Description |343|------|-------------|344| `get_line_item` | Get line item details |345| `create_line_item` | Create a new line item |346| `duplicate_line_item` | Duplicate an existing line item |347| `update_line_item` | Update line item properties (name, type, delivery rate, priority, cost, goal, end date) |348| `list_line_items_by_order` | List all line items for an order |349| `pause_line_item` | Pause a delivering line item |350| `resume_line_item` | Resume a paused line item |351| `archive_line_item` | Archive a line item |352| `approve_line_item` | Approve a line item (for approval workflows) |353354### Creative Tools355356| Tool | Description |357|------|-------------|358| `upload_creative` | Upload an image creative |359| `associate_creative_with_line_item` | Associate creative with line item |360| `upload_and_associate_creative` | Upload and associate in one step |361| `bulk_upload_creatives` | Upload all creatives from a folder |362| `get_creative` | Get creative details |363| `list_creatives_by_advertiser` | List creatives for an advertiser |364| `update_creative` | Update creative destination URL or name |365| `list_creatives_by_line_item` | List creatives associated with a line item |366| `create_third_party_creative` | Create HTML/JavaScript ad tag (DCM, custom HTML) |367| `get_creative_preview_url` | Generate preview URL to see creative on your site |368369### Advertiser Tools370371| Tool | Description |372|------|-------------|373| `find_advertiser` | Find advertiser by name |374| `get_advertiser` | Get advertiser details |375| `list_advertisers` | List all advertisers |376| `create_advertiser` | Create a new advertiser |377| `find_or_create_advertiser` | Find or create advertiser |378379### Verification Tools380381| Tool | Description |382|------|-------------|383| `verify_line_item_setup` | Verify line item configuration |384| `check_line_item_delivery_status` | Check delivery progress |385| `verify_order_setup` | Verify entire order setup |386387### Reporting Tools388389| Tool | Description |390|------|-------------|391| `run_delivery_report` | Generate delivery report (impressions, clicks, CTR, revenue) |392| `run_inventory_report` | Generate inventory report (ad requests, fill rate) |393| `run_custom_report` | Generate custom report with specified dimensions and metrics |394395### Workflow Tools396397| Tool | Description |398|------|-------------|399| `create_campaign` | Complete campaign creation workflow |400401## Example Usage with Claude402403```404User: List all delivering orders405406Claude: [Uses list_delivering_orders tool]407Here are the currently delivering orders:4081. Campaign IPhone 17 Pro 2025/2026 (ID: 123456)409 - Display line item: 45,000 impressions delivered410411User: Create a new campaign for "ACME Corp" ending December 31, 2025412413Claude: [Uses create_campaign tool]414I'll create the campaign with:415- Advertiser: ACME Corp416- Order: ACME Campaign 2025417- Line Item: Display418- End Date: December 31, 2025419420Campaign created successfully!421- Order ID: 789012422- Line Item ID: 345678423- 4 creatives uploaded and associated424```425426## Development427428### Setup429430```bash431# Clone the repository432git clone https://github.com/MatiousCorp/google-ad-manager-mcp.git433cd google-ad-manager-mcp434435# Install with dev dependencies436pip install -e ".[dev]"437```438439### Running Tests440441```bash442# Run all tests443pytest444445# Run with coverage446pytest --cov=gam_mcp --cov-report=html447448# Run specific test file449pytest tests/test_utils.py450```451452### Code Quality453454```bash455# Run linter456ruff check .457458# Run linter with auto-fix459ruff check . --fix460```461462## Roadmap463464The following features are planned for future releases:465466### Near-term467468- [ ] **Ad Unit Management** - List, get, and create ad units with hierarchy support469- [ ] **Placement Management** - Manage inventory placements and targeting470- [ ] **Forecast & Availability** - Check inventory availability and forecast impressions471- [x] **Creative Preview Links** - Generate preview URLs for creative-line item combinations472473### Medium-term474475- [ ] **Advanced Targeting** - Geographic, device, daypart, and custom key-value targeting476- [x] **Reporting Tools** - Generate and retrieve performance reports477- [ ] **Bulk Operations** - Batch updates for line items, creatives, and targeting478- [ ] **HTML5/Video Creatives** - Support for rich media and video creative uploads479480### Long-term481482- [ ] **Audience Management** - Create and manage audience segments483- [ ] **User & Permissions** - Manage users, roles, and order assignments484- [ ] **Yield Management** - Configure yield groups and optimization485- [ ] **Custom Reporting** - Scheduled reports with export capabilities486487### Community Requests488489Have a feature request? [Open an issue](https://github.com/MatiousCorp/google-ad-manager-mcp/issues) to suggest new functionality.490491## Contributing492493Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.494495## Changelog496497See [CHANGELOG.md](CHANGELOG.md) for version history.498499## API Version500501Uses Google Ad Manager SOAP API version `v202411`.502503## License504505MIT - see [LICENSE](LICENSE) for details.506507---508509## Need a Custom MCP Server?510511This project is built and maintained by **[Matious](https://matious.com)**.512513We 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.514515**What we build:**516- Custom MCP servers for any API or platform517- AI-powered automation workflows518- Claude integrations for business operations519520**Get in touch:** [matious.com](https://matious.com)521
Full transparency — inspect the skill content before installing.