Документация

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-ключи (ключи создаёт админ).

Ключ показывается один раз — скопируйте его.

Шаг 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:

Вариант A. Удалённое подключение по URL (с версии 0.9.6.2)

Самый быстрый способ, и единственный, который работает в браузерной версии Claude: трекер сам отдаёт MCP по HTTP через mcp.php.

  1. ⚙ → Пользователи → API-ключи, создайте ключ (Read — только аналитика, Write — ещё и управление).
  2. Нажмите рядом с ключом кнопку со ссылкой — в буфер попадёт готовый адрес:
https://ваш-трекер.example.com/mcp.php?k=ВАШ_КЛЮЧ
  1. В 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 появятся в списке. Закрыть окно недостаточно, конфиг читается только при старте.

Если сервер не появился:

Инструменты (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.

Безопасность

когда нужно управление.

Обновление

MCP поставляется вместе с проектом, поэтому штатное обновление (⚙ → Обновление или git pull) подтягивает новые файлы автоматически. После обновления, изменившего зависимости, выполните cd mcp && npm install. Если в новой версии поменялся список инструментов, переподключите коннектор в клиенте, чтобы он перечитал их.

← Назад
Telegram-бот
Все гайды →
Вики Orbitra
Исходник на GitHub: github.com/fenjo26/Orbitra.link/wiki
Все гайды
Документация

Быстрый старт: первая кампания

Короткий путь: установите трекер, создайте кампанию и получите первые клики и конверсии меньше чем за час.

Читать гайд →
Документация

Установка и обновление

Установите 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 и управляйте кампаниями обычными словами.

Читать гайд →