Google Ad Manager MCP Server

谷歌广告管理器MCP服务器

使用人工智能自动化谷歌广告管理器。 MCP服务器，让Claude、ChatGPT、Gemini、Cursor和VS Code等人工智能助手通过自然语言管理您的广告活动、行项目、创意等。

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

______________________________________________________________________

为什么存在

管理谷歌广告管理器很乏味。创建活动、上传创意和配置行项目需要通过复杂的UI进行无数次点击。

此MCP服务器改变了这一点。 将其连接到Claude，并通过对话管理您的整个广告运营：

• *“为12月31日结束的Nike创建新活动”*
• *“上载此文件夹中的所有创意，并将其与显示行项目相关联”*
• *“检查当前正在交付的订单”*

不再点击。告诉克劳德你需要什么。

特性

• 订单管理：列出、创建和管理订单
• 行项目管理：创建、复制和配置行项目
• 创造性管理：上传图片，与行项目关联，批量上传
• 广告商管理：查找、创建和列出广告商
• 验证工具：验证行项目设置，检查交付状态
• 活动工作流程：在一次操作中完成活动创建

安装

来自PyPI（推荐）

pip install google-ad-manager-mcp

或者使用紫外线：

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服务器框架
• 谷歌广告：Google广告管理器SOAP API客户端

配置

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

多网络支持

您可以使用单个服务器实例管理多个GAM网络。列出中的所有网络代码 GAM_NETWORK_CODES --第一个是默认值：

export GAM_NETWORK_CODES="31083078,22706375620,98765432"

所有工具都接受可选 network_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本地中间件，以下 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

端点

运行服务器

本地开发

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

云部署（铁路、Fly.io等）

1. 在云提供商中设置环境变量：

- GAM_CREDENTIALS_PATH：凭据路径（或使用机密） - GAM_NETWORK_CODE：您的广告管理器网络代码 - GAM_MCP_AUTH_TOKEN：安全身份验证令牌

1. 使用附带的Dockerfile进行部署

连接到AI助手

克劳德桌面（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"
      }
    }
  }
}

克劳德桌面（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"
      }
    }
  }
}

克劳德桌面（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桌面 -OpenAI于2025年3月采用MCP
• 光标 -支持MCP的AI驱动IDE
• VS代码 -通过MCP扩展
• Windsurf、Zed、Codeium -各种IDE集成

有关MCP服务器配置，请参阅每个客户端的文档。

MCP检验员测试

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

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

可用工具

订购工具

行项目工具

创造性工具

广告商工具

验证工具

报告工具

工作流工具

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

路线图

计划在未来的版本中提供以下功能：

短期

• \[ \] 广告单元管理 -使用层次结构支持列出、获取和创建广告单元
• \[ \] 安置管理 -管理库存放置和目标
• \[ \] 预测和可用性 -检查库存可用性和预测印象
• \[x\] 创意预览链接 -为创意行项目组合生成预览URL

中期

• \[ \] 高级目标定位 -地理、设备、日部分和自定义键值定位
• \[x\] 报告工具 -生成和检索绩效报告
• \[ \] 批量操作 -批量更新行项目、创意和目标
• \[ \] HTML5/视频创意 -支持富媒体和视频创意上传

长期

• \[ \] 观众管理 -创建和管理受众细分
• \[ \] 用户和权限 -管理用户、角色和订单分配
• \[ \] 收益管理 -配置产量组和优化
• \[ \] 自定义报告 -具有导出功能的计划报告

社区请求

有功能请求吗？ 打开一个问题 以建议新功能。

贡献

欢迎投稿！请参阅 贡献.md 作为指导方针。

更新日志

看 更改日志.md 版本历史。

API版本

使用Google广告管理器SOAP API版本 v202502.

许可证

麻省理工学院-见 许可证 了解详情。

______________________________________________________________________

需要自定义MCP服务器吗？

该项目由以下人员建造和维护 马蒂厄斯.

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

我们构建的内容：

• 为任何API或平台定制MCP服务器
• 人工智能驱动的自动化工作流程
• Claude业务运营集成

联系我们： matious.com