用途
Google Ad Manager MCP Server 是一个 MCP（Model Context Protocol）服务器，用于把 Google Ad Manager（GAM）接入 AI 助手。其目标是让使用者通过自然语言，而不是在 GAM 复杂界面中反复点击，来完成广告运营工作。
支持接入的 AI 助手包括 Claude、ChatGPT、Gemini、Cursor 和 VS Code 等 MCP 兼容客户端。项目由 Matious 构建。
主要能力
- 订单管理：列出、创建和管理订单。
- 订单项管理：创建、复制和配置订单项。
- 创意管理：上传图片、关联订单项、批量上传。
- 广告主管理：查找、创建和列出广告主。
- 验证工具：验证订单项设置、检查投放状态。
- 广告活动工作流：在一次操作中完成完整的广告活动创建。
示例用法包括：“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”。
使用方式
安装
推荐从 PyPI 安装。技术栈包括 FastMCP（带原生中间件支持的 MCP 服务器框架）和 googleads（Google Ad Manager SOAP API 客户端）。
配置
服务器使用环境变量进行配置。
多网络支持
可以在单个服务器实例中管理多个 GAM 网络。在 GAM_NETWORK_CODES 中列出所有网络代码，第一个为默认网络：所有工具都接受可选的 network_code 参数；省略时使用第一个（默认）网络。各网络共享同一服务账号凭据，只需确保服务账号邮箱已作为用户添加到每个网络中。
运行服务器
- 本地开发
- Docker 部署：Docker 镜像以非 root 用户（appuser）运行以提升安全性。可创建 docker-compose.yml 文件。
- 云部署（Railway、Fly.io 等）：在云服务商中设置环境变量
GAM_CREDENTIALS_PATH（凭据路径或使用 secrets）、GAM_NETWORK_CODE（Ad Manager 网络代码）、GAM_MCP_AUTH_TOKEN（安全认证令牌），使用附带的 Dockerfile 部署。
连接到 AI 助手
- Claude Desktop（推荐使用 uvx）：添加到
~/Library/Application Support/Claude/claude_desktop_config.json。 - Claude Desktop（Docker）：同样添加到上述配置文件。
- Claude Desktop（HTTP 模式）：当服务器以 HTTP 模式运行时使用。
- 带认证的远程服务器：远程部署并启用认证时使用。
其他 MCP 客户端：ChatGPT Desktop（OpenAI 于 2025 年 3 月采用 MCP）、Cursor（支持 MCP 的 AI IDE）、VS Code（通过 MCP 扩展）、Windsurf、Zed、Codeium 等 IDE 集成。具体配置请参考各客户端文档。
可用 MCP Inspector 进行测试。
安全特性
服务器使用 FastMCP 原生中间件实现 Bearer token 认证，遵循 MCP 安全最佳实践：
- FastMCP 原生中间件：使用 FastMCP 2.x 中间件进行正确的 MCP 生命周期管理。
- 加密安全令牌：使用
secrets.token_hex(32)生成。 - 防时序攻击：使用常量时间比较（
hmac.compare_digest）。 - 工具级认证：每次工具调用都验证认证。
- 审计日志：记录所有认证失败。
认证在工具级通过 FastMCP 的中间件系统强制执行：工具被调用时，中间件验证 Authorization 头；如果未配置令牌（GAM_MCP_AUTH_TOKEN 未设置），请求被允许；无效或缺失令牌会返回带有提示信息的 ToolError。对于远程部署，可设置固定认证令牌；如果未设置，启动时会生成随机令牌并显示在日志中。客户端必须在 Authorization 头中包含该令牌。
适用场景
适用于需要自动化 Google Ad Manager 广告运营的团队与个人，尤其是希望通过对话式 AI 助手创建广告活动、上传创意、配置订单项、检查投放状态的广告运营场景。也适合需要跨多个 GAM 网络统一管理，或需要将 GAM 接入自定义 AI 工作流的业务。
限制与规划
- 服务器使用 Google Ad Manager SOAP API 版本 v202502。
- 认证令牌未设置时请求会被允许，远程部署需自行设置固定令牌。
- 多网络共享同一服务账号凭据，需在每个网络中为该服务账号添加用户。
以下功能为未来版本规划（当前暂未提供）：广告单元管理（列出、获取、创建广告单元及层级支持）、展示位置管理、预测与可用性、创意预览链接、高级定向（地理、设备、时段、自定义键值）、报告工具（生成与获取效果报告）、批量操作（订单项、创意、定向的批量更新）、HTML5/视频创意（富媒体与视频创意上传）、受众管理、用户与权限、收益管理（收益组与优化配置）、自定义报告（带导出能力的定时报告）。
许可与贡献
项目使用 MIT 许可，详见 LICENSE。欢迎贡献，请参阅 CONTRIBUTING.md；版本历史见 CHANGELOG.md。功能请求可通过提交 issue 提出。
其他
该项目由 Matious 构建和维护，Matious 专注于为企业构建自定义 AI 工具和 MCP 服务器，可集成 CRM、ERP、广告平台或内部工具。联系地址：matious.com。
