MCP:追踪器里的 AI 助手
从 0.9.5.0 版本起,你可以通过 MCP server 把 AI 助手(Claude Desktop 和其他 MCP 客户端)连上 Orbitra — 它位于 mcp/ 文件夹。连接后,可以用大白话指挥追踪器:
"我过去 7 天的广告系列跑得怎么样?"
"给 offer #4 建 10 个广告系列 — 每个 GEO 一个:US、CA、GB、DE、FR。"
"添加域名 track.example.com,把广告系列 12 放到它的根路径上。"
服务器通过 HTTPS 使用个人 API key 与你的追踪器通信。它自己一侧不存储任何东西,只读密钥在物理上无法修改数据。
工作原理
Claude Desktop ──stdio──► mcp/src/index.js ──HTTPS + API key──► ваш Orbitra (api.php)
MCP server 是追踪器常规 API(api.php)之上的薄客户端。它只是把 API 动作包装成 AI 能理解的工具,并加了一道保险(只读密钥不能写)。
第 1 步:获取 API 密钥
在面板里:⚙ → AI / MCP 或 ⚙ → Users → API keys(密钥由管理员创建)。
- Read key — 仅分析(指标、列表、报表)。
- Write key — 再加管理(创建/编辑/删除广告系列、offer、域名……)。
密钥只显示一次 — 复制保存。
第 2 步:安装依赖
通过 install.sh 安装时,MCP 依赖自动装好。手动安装:
cd mcp
npm install
自检(启动服务器并打印工具列表;无需真实追踪器):
npm run smoke
对着真实追踪器检查:
ORBITRA_URL=https://tracker.example.com ORBITRA_API_KEY=your_key npm run smoke -- --ping
第 3 步:连接 Claude Desktop
Claude Desktop 配置文件:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
方式 A. 通过 URL 远程连接(0.9.6.2 版起)
最快的选项,也是唯一在浏览器版 Claude 里可用的方式:追踪器自己通过 mcp.php 在 HTTP 上提供 MCP。
- ⚙ → Users → API keys,创建密钥(Read — 仅分析,Write — 再加管理)。
- 点密钥旁边的链接按钮 — 一个现成的 URL 复制到剪贴板:
https://ваш-трекер.example.com/mcp.php?k=ВАШ_КЛЮЧ
- 在 Claude 里:Settings → Connectors → Add custom connector,粘贴 URL,起个名字,"Add"。
什么都不用装 — 你机器上既不需要 Node 也不需要代码仓库。
🔑 密钥直接放在 URL 里,因为连接器对话框没有密钥输入框、只支持 OAuth。把这种 URL 当密码对待:不要公开它;要切断访问,在 ⚙ → Users → API keys 里删除密钥 — URL 立即失效。只读密钥在物理上改不了任何东西。
工作原理。 mcp.php 实现了无会话的 MCP Streamable HTTP:每个 POST 都是一次自包含的 JSON-RPC 交换。它从 mcp/tools.json 取工具列表 — 该文件由 Node 服务器生成(node mcp/src/manifest.js),因此两种连接方式呈现完全相同的 41 个工具。工具调用以短命的 CLI 进程 cli/api_invoke.php 运行 — 追踪器不通过 HTTP 调用自己,否则在一台只有两个 PHP-FPM worker 的 VPS 上可能阻塞整站。
要求: PHP CLI(cron 已经需要它)且允许 proc_open。如果 php.ini 禁用了 proc_open,该端点会用明文告诉你 — 那就改用方式 B。PHP 路径可通过 mcp_php_binary 设置手动指定。
方式 B. Claude Desktop 本地服务器
⚠️ 这不是"Add custom connector"对话框。 Claude 里的 Connectors 分区只接受 HTTPS 上的远程 MCP 服务器并通过 OAuth 授权 — 这就是那里没有 API key 输入框的原因。Orbitra 服务器走 stdio:它在助手旁边本地启动,并注册在下面的配置文件里。把追踪器 URL 粘贴进连接器对话框不会工作。
可以直接从应用打开该文件:Settings → Developer → Edit Config。
添加一个 orbitra 服务器(mcp/src/index.js 用绝对路径):
{
"mcpServers": {
"orbitra": {
"command": "/usr/local/bin/node",
"args": ["/absolute/path/to/Orbitra/mcp/src/index.js"],
"env": {
"ORBITRA_URL": "https://tracker.example.com",
"ORBITRA_API_KEY": "ваш-api-ключ"
}
}
}
}
完全重启 Claude Desktop(macOS 上 ⌘Q)— Orbitra 工具会出现在列表里。只关窗口不够;配置只在启动时读取。
如果服务器没有出现:
- Node 路径。
command需要绝对路径:应用不从你的 shell 启动,nvm 或 Homebrew 的 Node 永远进不了它的PATH,服务器会静默启动失败。用which node(macOS/Linux)或where node(Windows)找到路径。 - 依赖未安装。
cd mcp && npm install。 - 密钥或 URL 不对。 单独验证:
ORBITRA_URL=... ORBITRA_API_KEY=... npm run smoke -- --ping。 - 创建或更新时
403 API key is read-only— 需要写密钥;只读密钥只能返回分析数据。
工具(41 个)
读取: orbitra_ping、orbitra_get_metrics、orbitra_get_chart、orbitra_list_campaigns、 orbitra_campaigns_stats、orbitra_get_campaign、orbitra_campaign_report、orbitra_list_offers、orbitra_get_offer、 orbitra_all_offers、orbitra_list_domains、orbitra_ssl_environment、orbitra_get_integration_code、 orbitra_list_app_configs、orbitra_telegram_status、orbitra_integrations_status、orbitra_list_traffic_sources、 orbitra_list_landings、orbitra_list_affiliate_networks、orbitra_list_conversions、 orbitra_recent_clicks、orbitra_system_status。
管理(需要写密钥): orbitra_create_campaign、orbitra_update_campaign、 orbitra_bulk_create_campaigns、orbitra_bulk_set_campaign_domain、orbitra_delete_campaign、orbitra_copy_campaign、 orbitra_create_offer、orbitra_update_offer、orbitra_delete_offer、orbitra_create_domain、 orbitra_delete_domain、orbitra_check_domain_dns、orbitra_reissue_ssl、orbitra_run_ssl_worker、 orbitra_save_app_config、 orbitra_create_traffic_source、 orbitra_list_traffic_source_templates、orbitra_create_landing。
进阶: orbitra_api_request — 直接调用任意 api.php 动作(兜底选项)。
大账户。 orbitra_list_campaigns 和 orbitra_list_domains 返回紧凑列表(id、name、alias、domain、link),带 ID 区间和域名过滤与分页 — 即使有几千个广告系列,响应依然很小。所有广告系列的统计来自 orbitra_campaigns_stats(响应较重),单个广告系列用 orbitra_campaign_report。要一次改很多广告系列的域名 — orbitra_bulk_set_campaign_domain:只改域名,流和 postback 不动,响应带上每个广告系列的新旧链接。orbitra_update_campaign 会保留流 ID、流名称、过滤器逻辑、offer 选择和 Bot Challenge。
完整参数参考见 mcp/README.md。
安全
- 把 API key 当密码对待。默认用 read 密钥;只在需要管理时用 write。
- 密钥只发往你的
ORBITRA_URL(Authorization: Bearer/X-Api-Key请求头)。 - 写操作走常规 API,和其他操作一样进入审计日志。
- 只读密钥在写尝试时得到
403,什么也不改。 ORBITRA_INSECURE=1关闭 TLS 校验 — 仅用于本地开发。
更新
MCP 随项目一起发布,所以常规更新(⚙ → Update 或 git pull)会自动带上新文件。某次更新改了依赖时,运行 cd mcp && npm install。如果新版本的工具列表变了,在客户端重连连接器,让它重新读取工具。
快速上手
从裸机服务器到第一条转化的九个步骤:安装、首次登录、域名、联盟与 offer、流量来源、广告系列、验证、消耗与统计。
阅读教程 →文档安装与更新
系统要求、一条命令的安装器、PHP 更新与安全公告、按 IP 访问后台、更新完整性校验,以及本地开发环境。
阅读教程 →文档从 Keitaro 迁移
通过 SQL dump 把设置从 Keitaro 迁到 Orbitra:迁移内容清单、导出脚本、导入步骤,以及导入后要检查的事项。
阅读教程 →文档从 Binom 迁移
通过 Binom v2 Public API 直接导入广告系列、offer、流等设置 — 无需 dump 文件,附字段映射说明。
阅读教程 →文档功能总览
所有功能一览:流量与方案、postback 与消耗、数据分析、基础设施与管理 — 每项都链接到详细页面,并附各版本的新增内容。
阅读教程 →文档广告系列与流
广告系列编辑器详解:设置标签页、计费模式、流类型与全部过滤器、方案、自动优化轮询、测试链接与重复点击防护。
阅读教程 →文档斗篷(参考文档)
斗篷完整参考:流设置、检测层、灵敏度、定向过滤器、JavaScript 验证、全局设置、判定结果与原因代码及诊断方法。
阅读教程 →文档浏览器检查
通过浏览器自报矛盾识别机器人、审核员虚拟机、模拟器和反检测浏览器:四种模式、特征清单、结果查看与安全启用步骤。
阅读教程 →文档落地页(参考文档)
落地页完整参考:本地、跳转、Preload 与 Action 四种类型,{offer} 宏、subid 传递、停留时长、JS adapter、PHP 落地页与故障排查。
阅读教程 →文档PWA 与 Web Push
PWA 落地页与自建 Web Push:构建器、域名绑定、VAPID 密钥、订阅者、消息与发送 cron、转化归因和故障排查。
阅读教程 →文档PWA 漏斗
PWA 落地页内的可配置漏斗:store/screen/instructions/push 步骤类型、逐屏追踪、统计维度与编辑器用法。
阅读教程 →文档转化弹窗(Conversion Popups)
在落地页上展示带 offer 按钮的弹窗:适用场景、Popup 标签页设置、触发条件与统计指标。
阅读教程 →文档会话录制与热力图
像视频一样回放真实访问,配合点击热力图与滚动图;含整站录制、Cookie 同意、存储上限与隐私说明。
阅读教程 →文档素材库完整参考
Gallery 页面、上传与软删除、MediaPicker 的尺寸契约(sizeContract)、格式与大小限制,以及视频支持。
阅读教程 →文档创意库
平台同步的创意与手动上传的草稿统一存放,自动绑定花费/收入/ROI,找出真正赚钱的创意。
阅读教程 →文档外部 PWA 与 Telegram 频道
把第三方 PWA 构建器接入流做 A/B,并把 Telegram 频道当作可归因的 offer 目的地。
阅读教程 →文档Postback 与转化
入站 postback 参数与状态映射、转化类型、出站 S2S postback、投递队列与测试器、转化导入和 Conversions API。
阅读教程 →文档花费(Costs)
从 Facebook、TikTok、Google Ads 和 push/pop 联盟导入花费并分摊到点击;含收入聚合器、代理佣金与排错。
阅读教程 →文档Push 与 Pop 联盟
接入 push/pop 联盟的花费导入与 zone 级优化:支持联盟列表、匹配规则与 Zone Killer 屏蔽烧钱 zone。
阅读教程 →文档Facebook / Meta
两套独立集成:从 Meta 导入广告花费,以及用 Conversions API 服务端发送转化事件,含浏览器匹配与排错。
阅读教程 →文档Dolphin / Fbtool
通过 Dolphin(Fbtool)API 实时接收 Facebook 消耗:兼容 Keitaro 的入站端点、API 密钥与活动参数配置、消耗分摊与验证。
阅读教程 →文档FB 评论清理器
按计划批量审核 Facebook 广告贴下的评论:停用词、正则、链接与联系方式规则,默认 dry-run、默认隐藏、操作可恢复。
阅读教程 →文档流量来源与联盟
配置漏斗两端的两个目录:约 200 个流量来源模板与约 440 个联盟模板,参数三元组、postback URL 与 offer 参数宏。
阅读教程 →文档报表、日志与指标
仪表盘、报表生成器、趋势与群组、流量日志与点击卡片,以及每个指标的计算方式。
阅读教程 →文档域名与 SSL
添加域名、把 DNS 指向服务器、自动签发 Let's Encrypt 证书,以及 Domains 页面上每个开关的作用。
阅读教程 →文档Cloudflare
通过 API 接入 Cloudflare:域名自动停放 A 记录、多账号、代理(橙色云朵)与 Flexible / Full / Strict SSL 模式。
阅读教程 →文档管理
用户、角色与按资源授权、两步验证、API 密钥、安全设置、geo 数据库、面板更新与系统状态。
阅读教程 →文档Telegram 机器人
在 Telegram 里管理追踪器:转化通知、每日摘要、统计命令,以及发到频道/群组的转化提醒。
阅读教程 →文档MCP:追踪器里的 AI 助手
把 Claude 或任何 MCP 客户端连上 Orbitra,用大白话管理广告系列:41 个工具、远程与本地两种连接方式、API 密钥安全。
阅读教程 →