MCP-сервер: работа с трекером через нейросеть
Начиная с версии 0.9.5.0 к Orbitra можно подключить ИИ-ассистента (Claude Desktop и другие MCP-клиенты) через MCP-сервер — он лежит в папке mcp/. После подключения трекером можно управлять на обычном языке:
«Как отработали кампании за последние 7 дней?»
«Создай 10 кампаний под оффер №4 — по одной на GEO: US, CA, GB, DE, FR.»
«Добавь домен track.example.com и повесь на его корень кампанию 12.»
Сервер общается с вашим трекером по HTTPS с помощью персонального API-ключа. Ничего не хранит на своей стороне, а ключи с правом только чтения физически не могут изменять данные.
Как это устроено
Claude Desktop ──stdio──► mcp/src/index.js ──HTTPS + API key──► ваш Orbitra (api.php)
MCP-сервер — это тонкий клиент к обычному API трекера (api.php). Он лишь удобно оборачивает действия API в инструменты, понятные нейросети, и добавляет защиту (read-ключи не могут писать).
Шаг 1. Получите API-ключ
В панели: ⚙ → ИИ / MCP или ⚙ → Пользователи → API-ключи (ключи создаёт админ).
- Read key — только аналитика (метрики, списки, отчёты).
- Write key — плюс управление (создание/редактирование/удаление кампаний, офферов, доменов…).
Ключ показывается один раз — скопируйте его.
Шаг 2. Установите зависимости
При установке через install.sh зависимости MCP ставятся автоматически. Вручную:
cd mcp
npm install
Самопроверка (поднимает сервер и печатает список инструментов, живой трекер не нужен):
npm run smoke
Проверка против живого трекера:
ORBITRA_URL=https://tracker.example.com ORBITRA_API_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 по HTTP через mcp.php.
- ⚙ → Пользователи → API-ключи, создайте ключ (Read — только аналитика, Write — ещё и управление).
- Нажмите рядом с ключом кнопку со ссылкой — в буфер попадёт готовый адрес:
https://ваш-трекер.example.com/mcp.php?k=ВАШ_КЛЮЧ
- В Claude: Settings → Connectors → Add custom connector, вставьте адрес, задайте имя, «Add».
Ставить ничего не нужно — ни Node, ни репозиторий на своей машине.
🔑 Ключ едет прямо в адресе, потому что диалог коннектора не имеет поля для ключа и умеет только OAuth. Считайте такой URL паролем: не публикуйте его, а чтобы закрыть доступ — удалите ключ в ⚙ → Пользователи → API-ключи, адрес сразу перестанет работать. Read-ключ физически не может ничего изменить.
Как это устроено. mcp.php реализует MCP Streamable HTTP без сессий: каждый POST — самодостаточный обмен JSON-RPC. Список инструментов он берёт из mcp/tools.json, который генерируется из Node-сервера (node mcp/src/manifest.js), поэтому два подключения показывают ровно один и тот же набор из 41 инструмента. Вызов инструмента выполняется коротким CLI-процессом cli/api_invoke.php — трекер не ходит сам к себе по HTTP, иначе на VPS с двумя PHP-FPM воркерами запрос мог бы заблокировать сайт.
Требования: PHP CLI (он и так нужен для крона) и разрешённый proc_open. Если proc_open отключён в php.ini, эндпоинт скажет об этом прямым текстом — тогда используйте вариант B. Путь к PHP можно задать вручную настройкой mcp_php_binary.
Вариант B. Локальный сервер для Claude Desktop
⚠️ Это не диалог «Add custom connector». Раздел Connectors в Claude принимает только удалённые MCP-серверы по HTTPS и авторизует их через OAuth — поэтому там нет поля для API-ключа. Сервер Orbitra работает по stdio: он запускается локально рядом с ассистентом и прописывается в файле конфигурации ниже. Адрес трекера, вставленный в диалог коннектора, работать не будет.
Открыть файл можно прямо из приложения: 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 (⌘Q на macOS) — инструменты Orbitra появятся в списке. Закрыть окно недостаточно, конфиг читается только при старте.
Если сервер не появился:
- Путь к Node. В
commandнужен абсолютный путь: приложение стартует не из вашего шелла, поэтому Node из nvm или Homebrew в его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на создание или изменение — нужен Write-ключ, Read-ключ отдаёт только аналитику.
Инструменты (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.
Управление (нужен write-ключ): 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, название, алиас, домен, ссылка) с фильтрами по диапазону ID и домену и постраничной выдачей — ответ остаётся маленьким и на тысячах кампаний. Статистику по всем кампаниям отдаёт orbitra_campaigns_stats (тяжёлый ответ), по одной — orbitra_campaign_report. Сменить домен у многих кампаний разом — orbitra_bulk_set_campaign_domain: меняется только домен, потоки и постбеки не трогаются, в ответе старая и новая ссылка каждой кампании. orbitra_update_campaign сохраняет ID потоков, их имена, логику фильтров, выбор оффера и Bot Challenge.
Полный справочник по параметрам — в mcp/README.md.
Безопасность
- Относитесь к API-ключу как к паролю. По умолчанию используйте read-ключ; write — только
когда нужно управление.
- Ключ уходит только на ваш
ORBITRA_URL(заголовкиAuthorization: Bearer/X-Api-Key). - Действия записи проходят через штатный API и попадают в аудит-логи, как обычные операции.
- Read-ключ при попытке записи получает ответ
403и ничего не меняет. ORBITRA_INSECURE=1отключает проверку TLS — только для локальной разработки.
Обновление
MCP поставляется вместе с проектом, поэтому штатное обновление (⚙ → Обновление или git pull) подтягивает новые файлы автоматически. После обновления, изменившего зависимости, выполните cd mcp && npm install. Если в новой версии поменялся список инструментов, переподключите коннектор в клиенте, чтобы он перечитал их.
Быстрый старт: первая кампания
Короткий путь: установите трекер, создайте кампанию и получите первые клики и конверсии меньше чем за час.
Читать гайд →ДокументацияУстановка и обновление
Установите Orbitra на чистый сервер Ubuntu или Debian одной командой и безопасно обновляйтесь до новых версий.
Читать гайд →ДокументацияМиграция из Keitaro
Перенесите кампании, офферы, источники и домены из Keitaro в Orbitra в один клик — что переносится и что проверить.
Читать гайд →ДокументацияМиграция из Binom
Перенесите кампании и потоки из Binom в Orbitra: что переносится автоматически, а что настроить вручную.
Читать гайд →ДокументацияВозможности Orbitra
Всё, что умеет Orbitra: кампании и потоки, клоакинг, лендинги, PWA, постбеки, расходы, отчёты и интеграции.
Читать гайд →ДокументацияКампании и потоки
Полный справочник: настройки кампаний, типы потоков, схемы, ротация, фильтры, тестовые ссылки и каждый параметр.
Читать гайд →ДокументацияКлоакинг
Полный справочник по клоакингу: уровни детекции, глобальные настройки, фильтры потоков, вердикты и отчёты.
Читать гайд →ДокументацияПроверка браузера
Как JS-проверка ловит ботов, виртуальные машины и эмуляторы через противоречия в окружении браузера.
Читать гайд →ДокументацияЛендинги
Типы лендингов, макрос {offer}, JS-адаптер, LeadForge и мульти-оффер лендинги — полный справочник.
Читать гайд →ДокументацияPWA-лендинги и Web Push
Собирайте устанавливаемые PWA-приложения и собирайте push-подписчиков: настройки, иконки, события и уведомления.
Читать гайд →ДокументацияPWA-воронка
Многошаговая PWA-воронка: приглашения к установке, отслеживание событий и возвратные уведомления.
Читать гайд →ДокументацияКонверсионные попапы
Показывайте реальные конверсии как попапы на странице: настройка, триггеры и размещение.
Читать гайд →ДокументацияЗаписи сессий и карта кликов
Воспроизводите реальные визиты, смотрите карты кликов и скроллов. Лимиты хранения и приватность.
Читать гайд →ДокументацияГалерея контента
Центральное хранилище иконок, скриншотов и креативов для PWA и лендингов.
Читать гайд →ДокументацияБиблиотека креативов
Храните креативы с отслеживанием по subid и тестируйте их в разных кампаниях.
Читать гайд →ДокументацияВнешние PWA и Telegram-каналы
Публикуйте PWA на внешних доменах и используйте Telegram-каналы как источник трафика.
Читать гайд →ДокументацияПостбеки и конверсии
Входящие постбеки, статусы и типы конверсий, исходящие S2S-постбеки в источник трафика.
Читать гайд →ДокументацияРасходы: импорт из рекламных кабинетов
Импорт расходов из Facebook, TikTok и Google Ads, обновление через API и крон — и как работает агрегатор доходов.
Читать гайд →ДокументацияPush и pop сети
Работа с пуш и поп источниками трафика: фиды, оптимизация зон и zone killer.
Читать гайд →ДокументацияFacebook / Meta integration
Импорт расходов из Meta Ads и Conversions API: серверные события с дедупликацией.
Читать гайд →ДокументацияDolphin / Fbtool — приём расходов (Keitaro Admin API)
Получайте расходы Facebook через API Dolphin (Fbtool) в реальном времени.
Читать гайд →ДокументацияЧистилка комментариев FB
Массовая модерация комментариев под рекламой Meta: скрывать, удалять и фильтровать по ключевым словам.
Читать гайд →ДокументацияИсточники трафика и партнёрские сети
Каталог 50+ источников трафика и 440+ сетей: шаблоны, параметры и адреса постбеков.
Читать гайд →ДокументацияОтчёты, логи и метрики
Конструктор отчётов, сохранённые отчёты, логи кликов и каждая метрика с пояснением.
Читать гайд →ДокументацияДомены и SSL
Добавление доменов, DNS, бесплатные сертификаты Let's Encrypt, редиректы, парковка и каждый переключатель на странице.
Читать гайд →ДокументацияCloudflare — DNS и SSL доменов
Как запускать домены кампаний через Cloudflare: DNS, режимы SSL и что отключить.
Читать гайд →ДокументацияАдминистрирование
Пользователи, роли и права, настройки безопасности, гео-базы, обновления и состояние системы.
Читать гайд →ДокументацияTelegram-бот
Управляйте трекером из Telegram: статистика, конверсии и алерты в чате.
Читать гайд →ДокументацияMCP-сервер: работа с трекером через нейросеть
Подключите Claude или любой MCP-клиент к Orbitra и управляйте кампаниями обычными словами.
Читать гайд →