Google Ad Manager MCP

Google Ad Manager MCP 服务

用 AI 自动化管理 Google Ad Manager。 这个 MCP 服务让 Claude、ChatGPT、Gemini、Cursor 和 VS Code 等 AI 助手能够通过自然语言管理广告系列、订单项、创意素材等。

由 Matious 构建 — 我们为企业构建定制 AI 工具和 MCP 服务。

---

为什么要构建它

管理 Google Ad Manager 很繁琐。创建广告系列、上传创意素材和配置订单项，都需要在复杂的界面中反复点击。

这个 MCP 服务改变了这一切。 将它连接到 Claude，通过对话管理所有广告业务：

• “为 Nike 创建一个新广告系列，结束日期为 12 月 31 日”
• “上传此文件夹中的所有创意素材，并将它们关联到 Display 订单项”
• “检查目前正在投放的订单”

不必再点击。只需告诉 Claude 你的需求。

功能

• 订单管理：列出、创建和管理订单
• 订单项管理：创建、复制和配置订单项
• 创意素材管理：上传图片、关联订单项、批量上传
• 广告客户管理：查找、创建和列出广告客户
• 验证工具：验证订单项设置、检查投放状态
• 广告系列工作流：一次操作即可完成广告系列创建

安装

从 PyPI 安装（推荐）

pip install google-ad-manager-mcp

或者使用 uv：

uv pip install google-ad-manager-mcp

从源代码安装

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

依赖项

• FastMCP：具备原生中间件支持的 MCP 服务框架
• googleads：Google Ad Manager SOAP API 客户端

配置

该服务使用环境变量进行配置：

变量	说明	必需
GAM_CREDENTIALS_PATH	服务账号 JSON 文件的路径	是
GAM_NETWORK_CODES	以逗号分隔的 GAM 网络代码列表（第一个为默认值）	是
GAM_MCP_TRANSPORT	传输模式：stdio 或 http	否（默认值：stdio）
GAM_MCP_HOST	服务主机（仅限 HTTP 模式）	否（默认值：0.0.0.0）
GAM_MCP_PORT	服务端口（仅限 HTTP 模式）	否（默认值：8000）
GAM_MCP_AUTH_TOKEN	身份验证令牌（仅限 HTTP 模式）	否（未设置时自动生成）

多网络支持

你可以通过一个服务实例管理多个 GAM 网络。在 GAM_NETWORK_CODES 中列出所有网络代码，第一个为默认值：

export GAM_NETWORK_CODES="31083078,22706375620,98765432"

所有工具都接受可选的 network_code 参数。省略时，将使用第一个（默认）网络。所有网络共用同一组服务账号凭据，只需确保服务账号邮箱已在每个网络中添加为用户。

Claude Code MCP 配置：

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

身份验证

该服务使用 FastMCP 原生中间件实现 Bearer 令牌身份验证，并遵循 MCP 安全最佳实践。

安全功能

• FastMCP 原生中间件：使用 FastMCP 2.x 中间件妥善管理 MCP 生命周期
• 密码学安全令牌：使用 secrets.token_hex(32) 生成
• 防止计时攻击：使用恒定时间比较（hmac.compare_digest）
• 工具级身份验证：每次调用工具时都会验证身份
• 审计日志：记录所有身份验证失败事件

工作原理

使用 FastMCP 的中间件系统在工具级别强制执行身份验证：

• 调用工具时，中间件会验证 Authorization 标头
• 如果未配置令牌（未设置 GAM_MCP_AUTH_TOKEN），则允许请求
• 令牌无效或缺失时，会返回带有说明性消息的 ToolError

设置

对于远程部署，请设置固定的身份验证令牌：

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

如果未设置，启动时会生成一个随机令牌，并显示在日志中。

客户端必须在 Authorization 标头中包含令牌：

Authorization: Bearer your-generated-token

端点

端点	描述
/mcp	MCP 协议端点（在工具调用时验证身份）

运行服务

本地开发

# 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 部署

出于安全考虑，Docker 镜像以非 root 用户（appuser）运行。

构建镜像

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

运行容器

# 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 startup logs (includes generated auth token if not set)
docker logs gam-mcp

# Follow logs
docker logs -f gam-mcp

Docker Compose

创建一个 docker-compose.yml 文件：

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

使用以下命令运行：

docker-compose up -d

验证容器

# 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}'

云部署（Railway、Fly.io 等）

1. 在云服务提供商处设置环境变量：

   • GAM_CREDENTIALS_PATH：凭据路径（或使用密钥）
   • GAM_NETWORK_CODE：您的 Ad Manager 网络代码
   • GAM_MCP_AUTH_TOKEN：安全的身份验证令牌

2. 使用随附的 Dockerfile 部署

连接到 AI 助手

Claude Desktop（uvx - 推荐）

这是将此服务与 Claude Desktop 搭配使用的最简单方式。将配置添加到 ~/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）

将配置添加到 ~/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 模式）

如果以 HTTP 模式运行服务：

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

带身份验证的远程服务

如果启用了身份验证并进行远程部署：

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

其他 MCP 客户端

此服务兼容任何 MCP 客户端，包括：

• ChatGPT Desktop - OpenAI 于 2025 年 3 月采用了 MCP
• Cursor - 支持 MCP 的 AI 驱动 IDE
• VS Code - 通过 MCP 扩展
• Windsurf、Zed、Codeium - 各类 IDE 集成

请参阅各客户端的文档，了解 MCP 服务配置。

使用 MCP Inspector 进行测试

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

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

可用工具

订单工具

工具	描述
list_delivering_orders	列出所有包含正在投放的订单项的订单
get_order	按 ID 或名称获取订单详情
create_order	创建新订单
find_or_create_order	查找现有订单或创建新订单

订单项工具

工具	描述
get_line_item	获取订单项详情
create_line_item	创建新的订单项
duplicate_line_item	复制现有订单项
update_line_item	更新订单项属性（名称、类型、投放速率、优先级、费用、目标、结束日期）
list_line_items_by_order	列出某个订单的所有订单项
pause_line_item	暂停正在投放的订单项
resume_line_item	恢复已暂停的订单项
archive_line_item	归档订单项
approve_line_item	批准订单项（用于审批工作流）

创意素材工具

工具	描述
upload_creative	上传图片创意素材
associate_creative_with_line_item	将创意素材关联到订单项
upload_and_associate_creative	一步完成上传和关联
bulk_upload_creatives	上传文件夹中的所有创意素材
get_creative	获取创意素材详情
list_creatives_by_advertiser	列出某个广告主的创意素材
update_creative	更新创意素材的目标 URL 或名称
list_creatives_by_line_item	列出与某个订单项关联的创意素材
create_third_party_creative	创建 HTML/JavaScript 广告代码（DCM、自定义 HTML）
get_creative_preview_url	生成预览 URL，以便在您的网站上查看创意素材

广告主工具

工具	描述
find_advertiser	按名称查找广告主
get_advertiser	获取广告主详情
list_advertisers	列出所有广告主
create_advertiser	创建新的广告主
find_or_create_advertiser	查找或创建广告主

验证工具

工具	描述
verify_line_item_setup	验证订单项配置
check_line_item_delivery_status	检查投放进度
verify_order_setup	验证整个订单设置

报告工具

工具	描述
run_delivery_report	生成投放报告（展示次数、点击次数、点击率、收入）
run_inventory_report	生成库存报告（广告请求、填充率）
run_custom_report	使用指定的维度和指标生成自定义报告

工作流工具

工具	描述
create_campaign	完整的广告系列创建工作流

使用 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

开发

设置

# 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]"

运行测试

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_utils.py

代码质量

# Run linter
ruff check .

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

路线图

计划在未来版本中推出以下功能：

短期

• 广告单元管理 - 列出、获取和创建广告单元，并支持层级结构
• 广告位管理 - 管理库存广告位和定位
• 预测与可用性 - 检查库存可用性并预测展示次数
• 创意预览链接 - 为创意与订单项组合生成预览 URL

中期

• 高级定位 - 地理位置、设备、时段和自定义键值定位
• 报告工具 - 生成和获取效果报告
• 批量操作 - 批量更新订单项、创意和定位
• HTML5/视频创意 - 支持富媒体和视频创意上传

长期

• 受众管理 - 创建和管理受众群体
• 用户与权限 - 管理用户、角色和订单分配
• 收益管理 - 配置收益组和优化
• 自定义报告 - 可定时生成并支持导出的报告

社区请求

有功能请求？请提交 issue以建议新功能。

贡献

欢迎贡献！请参阅CONTRIBUTING.md了解指南。

更新日志

请参阅CHANGELOG.md查看版本历史。

API 版本

使用 Google Ad Manager SOAP API 版本 v202502。

许可证

MIT - 详情请参阅 LICENSE。

---

需要定制 MCP 服务？

本项目由 Matious 构建和维护。

我们专注于构建可与现有系统集成的定制 AI 工具和 MCP 服务。无论您需要将 Claude 连接到 CRM、ERP、广告平台还是内部工具，我们都可以提供帮助。

我们构建的内容：

• 适用于任何 API 或平台的定制 MCP 服务
• AI 驱动的自动化工作流
• 用于业务运营的 Claude 集成

联系我们： matious.com