Orbiads

OrbiAds — Google Ad Manager MCP 服务

English · Français

_{为 AI Agent 提供托管式 MCP 服务，并提供用于终端和 CI 工作流的 Python 命令行工具。}

OrbiAds 是一个托管式 Google Ad Manager MCP 服务，让 AI 助手——Claude、ChatGPT、Gemini、Cursor 和 OpenAI Codex——能够通过自然语言直接访问 Google Ad Manager。它基于当前 GAM API（v202605），覆盖广告系列、订单、广告项、创意素材、广告资源、定向和报告等领域的 270 多项操作，并提供 OAuth 和写入前确认防护机制。

→ 在 orbiads.com 免费开始使用 · ★ 为此仓库点星

---

3 分钟快速体验

托管式 MCP，无需本地安装

1. 在 orbiads.com 创建免费 OrbiAds 账户，并连接 Google Ad Manager。
2. 将此 MCP 端点添加到 Claude、ChatGPT、Gemini、Cursor、Codex 或 Warp：

   https://orbiads.com/mcp
   

3. 向你的 Agent 提问：

   Connect to my GAM account and show me my active networks.
   

CLI 冒烟测试

pip install orbiads-cli
orbiads auth login
orbiads network info

想了解更详细的配置流程？请从 CLI 指南或 Agent 安装指南开始。

---

可信度信息

信号	状态	链接
公开仓库	OrbiAds MCP 发行版的 MIT 许可镜像	LICENSE
PyPI CLI	以 orbiads-cli 发布，用于终端和 CI 工作流	pypi.org/project/orbiads-cli
托管式 MCP	使用 OAuth 的远程 Streamable HTTP 端点	https://orbiads.com/mcp
Glama	已编入索引的 MCP 注册表页面	glama.ai
MCP.so	已编入索引的 MCP 目录页面	mcp.so
官方 MCP 注册表	server.json 清单已准备好，可提交至注册表	server.json
Smithery	已准备好提交托管式／外部 MCP 列表	smithery.ai/new
安全模型	写入操作遵循计划 → 确认 → 执行流程	安全文档

---

两种连接方式

OrbiAds 提供两种集成方式——选择适合你工作流的一种。

选项 A：MCP 服务（AI Agent）

通过托管式 MCP 端点将你的 AI 助手（Claude、ChatGPT、Gemini）连接到 GAM。支持对话式交互、引导操作，且无需安装。

MCP endpoint: https://orbiads.com/mcp

选项 B：CLI（终端和脚本）

面向开发者、CI/CD 流水线和无头自动化的轻量级 Python CLI。相同的 API、相同的额度、相同的安全护栏。

pip install orbiads-cli
orbiads auth login
orbiads network info

重要

Windows/macOS/Linux PATH 警告：如果通过 pip 安装 CLI（尤其是使用 --user 时），请确保将 Python 脚本目录添加到用户的 PATH 中。否则，终端和本地 AI Agent（如 Claude Code、Cursor 或 Gemini）将无法找到或执行 orbiads 命令。有关快速设置命令，请参阅 CLI 指南中的故障排除部分。

对比

标准	MCP 服务	CLI
接口	AI Agent（Claude、ChatGPT、Gemini）	终端 / 命令行
安装	将 URL 粘贴到 Agent 设置中	pip install orbiads-cli
身份验证	通过浏览器进行 OAuth（自动）	OAuth 设备流（显示代码）
最适合	探索、对话、引导式工作流	脚本、CI/CD、无头自动化
输出格式	通过 Agent 提供自然语言	JSON 或结构化表格
额度	相同的消耗表	相同的消耗表
离线使用	不支持 — 需要互联网连接	不支持 — 需要互联网连接
是否需要 Python	否	是（3.10+）

两种方式共用相同的后端、额度和安全护栏。

CLI 快速参考

命令	说明
orbiads auth login	通过 Google OAuth 设备流进行身份验证
orbiads auth status	检查身份验证状态
orbiads network info	显示当前 GAM 网络的详细信息
orbiads network list	列出可访问的 GAM 网络
orbiads orders list	列出网络中的订单
orbiads line-items list --order ID	列出某个订单的广告项
orbiads creatives list	列出创意素材
orbiads inventory ad-units	列出广告单元
orbiads forecast check --ad-unit ID	检查广告库存可用性
orbiads report run --template ID	运行投放报告

完整命令参考：orbiads.com/docs/cli/commands

---

安装指南

OrbiAds 根据你的环境提供三种集成方式。

1. 零安装 MCP 服务（ChatGPT、Gemini、Claude Desktop）

使用 Model Context Protocol 将 AI 助手连接到我们托管的服务：

• Claude Desktop：将以下内容添加到你的 claude_desktop_config.json：

  {
    "mcpServers": {
      "orbiads": {
        "type": "http",
        "url": "https://orbiads.com/mcp"
      }
    }
  }
  

• Gemini / AI Studio：前往 Tools → MCP configuration → Add https://orbiads.com/mcp
• ChatGPT：前往 Settings → Connectors → Add connector → MCP URL：https://orbiads.com/mcp
• GLAMA / MCP Registry：通过 glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP 直接在浏览器中访问、测试并连接该服务
• 其他环境（Cursor、Codex、Warp）：将 https://orbiads.com/mcp 端点添加到配置中，并将 AGENTS.md 复制到项目根目录。

2. Claude Code 插件（斜杠命令）

将 /adops 命令集直接添加到 Claude Code CLI 终端：

claude plugin install orbiads

3. Agent Skills（结构化工作流）

将基于 Markdown 的指南永久安装到 Claude Code 的记忆中：

1. 在本地克隆此仓库。
2. 运行技能安装程序：

   ./install.sh skills --copy
   

此操作会将我们整理合并后的 6 个技能文件复制到你的 ~/.claude/skills/ 目录。Claude Code 会自动运用这些文件，避免产生幻觉，并严格遵循先规划再修改的工作流。

→ 安装指南：Claude · ChatGPT · Gemini · OpenAI Codex

---

什么是 OrbiAds？

OrbiAds 是一个托管式 MCP 服务，可将你的 AI 助手直接连接到 Google Ad Manager（GAM）。无需在 GAM 界面中逐步点击，也无需编写 API 脚本，只需用普通语言描述你的需求——OrbiAds 会处理 API 调用、护栏和审计跟踪。

You: "Check inventory availability on the homepage banner for a 300x250 in France next week"
OrbiAds: [runs forecast] → Available: 1.2M impressions. Pressure: low. Safe to traffic.

You: "Create the line item for Renault, €15 CPM, Monday to Friday"
OrbiAds: [applies guardrails] → Preview ready. Confirm to push?

无需脚本。无需管理 API 令牌。无需切换标签页。

---

适用人群

• AdOps 经理：每天处理广告活动投放，希望提高效率且避免出错
• 发布商：管理自己的 GAM 网络，希望借助 AI 优化工作流
• 媒体代理机构：运营多个 GAM 账户，希望采用一致且可审计的流程
• 开发者：基于 Claude、ChatGPT 或 Gemini 构建 AdOps 自动化

---

支持的 AI 平台

平台	设置指南	模式
Claude（Desktop / claude.ai / Claude Code）	docs/install/claude.md	插件 + MCP 远程连接
ChatGPT（Pro connector）	docs/install/chatgpt.md	MCP 远程连接（HTTP）
Gemini	docs/install/gemini.md	MCP 远程连接
GLAMA（MCP registry）	glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP	MCP registry
Cursor / Codex / Warp / 其他	AGENTS.md	AGENTS.md + MCP wiring

所有平台都连接到同一个托管 MCP 端点：https://orbiads.com/mcp。

---

7 个斜杠命令

安装插件后，可直接在 Claude Code 中使用以下 /adops 命令。

命令	功能
/adops campaign	读取实时状态、规划部署、试运行（ExecutionPlan）、部署、暂停、回滚——必须经过 plan→confirm→execute 确认流程
/adops audit	多维度账户审计：投放、广告资源、安全、创意素材、账单
/adops report	自定义报告、投放查询、CSV 导出、账单摘要、预测
/adops deal	PMP 交易、私有竞价、Marketplace PG/PD 提案
/adops creative	上传创意素材、QA 合规检查、SSL 验证、预览 URL、关联广告订单项
/adops inventory	浏览广告单元、管理广告位和定向分类体系、运行蓝图
/adops admin	团队、站点、标签、自定义字段、网络设置（仅 MCP 接口）

包含内容（MCP 工具与技能）

OrbiAds 将 Google Ad Manager API 映射为父级工具和数百项操作，并将其组织为 6 个核心领域 Agent 技能以及一个编排器，以保持上下文使用简洁。请参阅 docs/tool-matrix/README.md，了解实时生成的工具和操作数量。

点击下方任一领域，查看所包含的工具和功能：

1. 广告活动与创意素材 QA (orbiads-campaigns)

• campaign — 读取实时广告活动状态、制定部署计划、试运行、部署、暂停和回滚广告活动。
• orders — 创建和列出订单、联系人及角色。
• line_items — 定义广告项投放规则、CPM 和定向逻辑。
• creatives — 上传创意素材（图片、HTML5、视频/音频）并配置原生样式。
• creative_assets — 管理关联的图片和文件资源。
• creative_qa — 审核点击跟踪器、执行合规扫描并验证 SSL 证书。
• creative_wrapper_skill — 管理第三方包装器和投放预设。
• formats — 探索并配置广告创意素材格式。
• jobs & gam_jobs — 监控异步广告活动编译和部署工作流。

2. 库存与定向 (orbiads-inventory)

• inventory — 获取广告单元树和尺寸，并生成 ads.json 清单。
• placements — 创建、更新和列出广告版位组。
• targeting — 管理自定义定向键/值、国家和类别。
• audiences — 获取并修改第一方受众细分。
• blueprint — 生成并推送结构化的网络库存蓝图。

3. 报告与预测 (orbiads-reporting)

• reporting — 使用模板运行自定义报告、检查广告项投放情况并集成 GA4。
• preview — 验证库存覆盖范围并导出预览 URL。
• pql — 运行原始 PQL 数据库查询。

4. 程序化交易 (orbiads-deals)

• deals — 管理 PMP 交易、私有竞价和市场买家。
• companies — 管理代理商和广告主的公司资料。

5. 网络管理 (orbiads-admin)

• gam_admin — 访问高级字段、网络标签、团队和站点记录。
• gam_features — 查询已启用的 Google Ad Manager Beta 版和系统功能。
• network — 列出可访问的网络并切换当前网络上下文。
• settings — 配置默认 CPM、投放节奏和品牌命名模板。
• tenant_catalog — 访问租户专属目录。

6. 审计与结算 (orbiads-audit)

• audit_skill — 执行自动化安全、规范性和包装器覆盖率审计。
• billing — 获取信用额度余额和交易历史记录。
• audit — 搜索网络审计日志。

请参阅 docs/tool-matrix/README.md，了解完整的对等矩阵，其中详细列出了全部 270 多项操作的确切成本、写入操作和参数。

---

安全设计

每项写入操作都需要先预览明确的 ExecutionPlan 并提供确认令牌。不会有广告活动意外上线。

• 先规划，再修改：针对广告活动、交易和产品的写入操作，推送前先预览已签名的 ExecutionPlan
• 试运行模式：所有部署操作均支持试运行 — confirmationToken 有效期为 300 秒
• 预测关卡：提交库存前，先验证可用性
• 审计跟踪：记录每项操作的执行者、操作内容、时间及结果
• 额度保护：读取操作始终免费，写入操作会透明扣除额度

---

快速开始（3 步）

1. 创建免费账户

访问 orbiads.com 并注册。你将获得 5 个免费额度 — 无需信用卡。

2. 连接 Google Ad Manager

在 OrbiAds 控制面板中，点击 Connect GAM，并使用 Google 账号授权。OrbiAds 使用 OAuth——你的 GAM 凭据不会离开 Google 的基础设施。

3. 配置你的 AI 助手

选择你的平台并按照指南操作：

• Claude 设置 →
• ChatGPT 设置 →
• Gemini 设置 →
• 其他工具（Cursor、Codex、Warp）→

然后从这句话开始：

“连接我的 GAM 账号，并显示我的活跃网络”

---

MCP 服务详情

属性	值
端点	https://orbiads.com/mcp
传输方式	streamable-http（默认）· sse
身份验证	OAuth 2.0——通过 OrbiAds 使用 Google 账号
GAM API 版本	v202605
MCP 协议	2025-03-26

---

仓库结构

skills/           ← orchestrator skill + 6 consolidated dual-surface domain skills (generated)
                     Each domain skill has SKILL.md (thin) + references/actions.md (full catalogue)
commands/         ← 7 /adops slash commands for Claude Code
agents/           ← Parallel audit subagents (audit-delivery, audit-inventory, …)
hooks/            ← Claude Code hooks (hooks.json)
cli/              ← OrbiAds CLI package (pip install orbiads-cli)
docs/             ← Installation guides, tool matrix, custom-skill authoring guide
_docs/            ← Internal: legacy tool mapping, anti-collision rules
.claude-plugin/   ← Claude plugin manifest (plugin.json, marketplace.json)
AGENTS.md         ← Cross-LLM contract for Cursor, Codex, Gemini, Warp, etc.
CLAUDE.md         ← Claude Code project guidance

技能和工具矩阵均由后端目录自动生成——请勿手动编辑。生成内容与手动编写内容的划分详见 CLAUDE.md。

---

定价

方案	价格	积分
试用	免费	5 积分（无需银行卡）
Starter	€39/月	50 积分/月
Early Access	€29/月 ← 永久锁定此价格	50 积分/月
Pack S	€29（一次性）	+50 积分
Pack L	€45（一次性）	+100 积分

读取始终免费。积分仅在写入和部署操作时扣除。

免费开始 →

---

许可证

本仓库的内容——分发脚手架、技能、Agent、工作流、JSON 架构、CLI 客户端、平台集成清单、文档和示例——均依据 MIT 许可证发布。

连接到托管端点 https://orbiads.com/mcp 的 OrbiAds MCP 服务后端和 Cloud Run 服务不在本仓库中，受单独的专有条款约束——参阅 orbiads.com 上的条款。