Bitrix24 MCP Bridge

Локальный MCP-сервер, дающий ИИ-агенту доступ к задачам, проектам и чатам Bitrix24 (чтение и — для вызовов из каталога — выполнение действий) — в объёме прав пользователя, через браузерное расширение, переиспользующее живую сессию. Без прав администратора и без официального REST-вебхука.

ИИ-агент ─stdio─► MCP-клиент ─UDS(bridge.sock)─► daemon ─WS(127.0.0.1:39917, токен+Origin)─► Расширение (вкладка портала)
                                                                                               │ fetch + свежий sessid + cookie
                                                                                               ▼
                                                                                   Bitrix24 (задачи / группы / чаты)

Быстрый старт

# 1. Настроить портал через npx — без глобальной установки (интерактивно): токен +
#    первый портал + config.json + actions.json + расширение
npx -y bitrix24-mcp-bridge setup

# 2. Зарегистрировать сервер у MCP-клиента (пример — Claude Code); каждый запуск идёт через npx
claude mcp add bitrix24-bridge -s user -- npx -y bitrix24-mcp-bridge

Пакет опубликован в npm registry как bitrix24-mcp-bridge (бинарь внутри называется bitrix24-bridge, но npx bitrix24-mcp-bridge резолвит его напрямую, т.к. в package.json он объявлен под обоими именами). Глобальная установка (npm i -g bitrix24-mcp-bridge) тоже работает и чуть быстрее стартует (без резолва npx при каждом запуске MCP-клиента) — тогда в шаге 2 подставь -- bitrix24-bridge вместо -- npx -y bitrix24-mcp-bridge.

Затем — два ручных шага, которые нельзя автоматизировать:

1. Загрузить расширение. chrome://extensions → включить Developer mode → Load unpacked → выбрать ~/.bitrix24-mcp-bridge/extension/.

2. Открыть залогиненную вкладку нужного портала и держать её открытой.

Готово. Агент видит инструменты bitrix_*; bitrix_status покажет, какие порталы подключены. Bun нужен только мейнтейнерам — конечному пользователю он не требуется.

Что делает setup

• Первый запуск (нет config.json): спрашивает origin портала и его alias, генерирует общий токен (crypto.randomBytes(32)), пишет ~/.bitrix24-mcp-bridge/config.json, кладёт стартовый actions.json (каталог методов) и материализует расширение в ~/.bitrix24-mcp-bridge/extension/ (статичные JS-бандлы + config.json + manifest.json, собранный под ваши порталы).

• Повторный запуск (config уже есть): открывает меню правки — [a] добавить портал, [r] удалить, [e] изменить origin, [d] сменить портал по умолчанию, [p] порт, [t] ротировать токен, [u] обновить расширение из установленного пакета, [q] выход.

Обновление пакета почти полностью автоматическое:

• Каталог — новые записи дописываются в ваш ~/.bitrix24-mcp-bridge/actions.json при следующем старте (в stderr — [catalog] added N new entries…). Ваши записи и правки не трогаются, а запись, которую вы удалили сами, назад не возвращается: доставленные ключи помечаются в catalog-state.json, поэтому удаление считается решением, а не пробелом.

• Файлы расширения в ~/.bitrix24-mcp-bridge/extension/ обновляются там же автоматически, если версия пакета изменилась ([extension] refreshed …), — запускать setup → [u] вручную больше не нужно.

• Один ручной шаг остаётся: нажать «Обновить» на расширении в chrome://extensions и перезагрузить вкладку портала. Программно это сделать нельзя — Chrome перечитывает файлы unpacked-расширения только сам. Пока этого не сделано, bitrix_status возвращает warning с версиями моста и расширения, так что рассинхрон виден сразу, а не всплывает необъяснимой ошибкой.

Мультипортальность поддержана: каждый портал — отдельная запись, а в манифесте расширения matches/host_permissions перечисляют ровно сконфигурированные origin'ы (least-privilege на origin).

daemon читает config.json только при старте, поэтому setup сам останавливает работающий daemon после любой правки, затрагивающей конфиг — следующий вызов агента поднимет новый daemon с актуальным конфигом. Если daemon почему-то не остановился (не было соединения), останови его вручную (pkill -f -- --daemon). Дополнительно:

• сменили набор порталов (add/remove/edit) → перезагрузить расширение в chrome://extensions;

• сменили порт или токен → переоткрыть вкладку портала.

Related MCP server: Networking MCP

Инструменты

Помимо bitrix_help / bitrix_status / bitrix_call, мост регистрирует типизированные обёртки над каталогом (разумные дефолты + схема параметров). Регистрируются только те, чьё имя есть в actions.json. Точная выборка — через необязательный params (мержится последним, перекрывает дефолты). Каждый принимает необязательный portal (alias; по умолчанию — из config.json). Обёртки в основном read-only; мутирующие помечены ⚠. bitrix_call выполняет любой разрешённый каталогом вызов, включая мутирующие.

bitrix_help — единственный источник конвенций params (select/filter/order/пагинация, имена полей). Он отдаёт docs/api-notes.md, так что любому агенту не нужен доступ к репозиторию.

Архитектура

Модель — один долгоживущий daemon + N тонких клиентов:

• daemon (bitrix24-bridge --daemon) владеет тремя ресурсами: WS-портом 127.0.0.1:39917, подключениями расширений (маршрутизация запросов по Origin вкладки к нужному порталу) и Unix-domain-сокетом ~/.bitrix24-mcp-bridge/bridge.sock (права 0600).

• MCP-клиент (bitrix24-bridge, без флагов) — то, что запускает ваш MCP-хост по stdio. Это тонкий UDS-клиент: он сам поднимает daemon, если сокета ещё нет, и подключается к нему.

Зачем так: раньше каждый MCP-клиент пытался открыть WS-порт сам, и второй экземпляр (или health-probe хоста) падал с конфликтом порта. Теперь порт держит только daemon, а любое число клиентов и проб сосуществуют через сокет. Daemon сам завершается по простою (~5 минут без клиентов).

Состояния (что видит агент)

• unconfigured — config.json ещё нет. Сервер всё равно стартует по stdio и регистрирует только bitrix_help + bitrix_status, которые направляют выполнить bitrix24-bridge setup. Настройка никогда не происходит в чате.

• configured, вкладка закрыта — портал сконфигурирован, но нет открытой залогиненной вкладки → bitrix_status покажет портал как не подключённый; откройте вкладку.

• live — вкладка открыта, расширение подключено, вызовы проходят.

Конфигурация

Runtime-домашняя папка — ~/.bitrix24-mcp-bridge/ (или $BITRIX24_MCP_BRIDGE_HOME). В ней: config.json, actions.json, bridge.sock, extension/.

Разрешение настроек слоями (побеждает верхний): env → .env (только для разработки) → ~/.bitrix24-mcp-bridge/config.json. Каталог методов по умолчанию берётся из ~/.bitrix24-mcp-bridge/actions.json; явный BITRIX_CATALOG (или catalog в config) по-прежнему поддержан.

Безопасность и модель доверия

Это research/PoC-инструмент в публичном репозитории. Прочтите перед использованием.

Граница доверия — локальная машина. daemon слушает только 127.0.0.1, требует токен первым сообщением и проверяет Origin (защита от cross-site WebSocket hijacking). Но сама привилегия — живая аутентифицированная сессия Bitrix24 — физически в расширении, а не в сервере. Отсюда:

• Граница — это allowlist каталога, не режим чтения. Мост выполняет только именованные вызовы из actions.json — теперь среди них могут быть мутирующие. Общий локальный токен (риск G7) в write-режиме означает: процесс, знающий токен и порт демона, может выполнять эти действия в объёме прав пользователя. Внутри разрешённого действия значения params не инспектируются — для мутирующего вызова это означает полный контроль агента над телом запроса в рамках этого действия. Держи actions.json под контролем — это и есть граница возможностей агента.

• Токен — единственная защита loopback-WS. Генерируйте длинный и случайный — setup использует crypto.randomBytes(32). Токен отсекает случайные подключения, но не является границей против локального атакующего: любой локальный процесс, знающий токен, может управлять мостом в объёме сессии.

• Токен и WS живут только в ISOLATED-мире расширения. Страница портала (MAIN world) не может прочитать config.json расширения, потому что запись помечена use_dynamic_url: true — URL ресурса непредсказуем со страницы. Подробности — в extension/README.md.

• UDS-граница — права ФС. Сокет bridge.sock создаётся с режимом 0600.

• Origin-allowlist. daemon отклоняет WS-подключения, чей Origin не входит в сконфигурированный набор порталов.

Вывод: запускайте только на доверенной машине, где вы контролируете локальные процессы; не используйте на общих или недоверенных хостах.

Полный операционный гайд и диагностика — docs/RUNBOOK.md.

Разработка

Bun — инструмент разработчика/мейнтейнера (конечному пользователю не нужен).

bun install
bun run src/index.ts            # MCP-клиент (default); сам поднимет daemon
bun run src/index.ts --daemon   # daemon вручную
bun run src/index.ts setup      # интерактивная настройка
bun test                        # юнит-тесты (bun:test)
bun run typecheck               # tsc --noEmit (сервер + extension)
bun run build:dist              # бандл сервера → dist/cli.js
bun run build:ext               # dev-сборка расширения → extension/dev/ (загружаемое)
bun run sync:runtime            # применить репо-изменения к живому daemon (см. ниже)

.env — только dev-оверрайды (gitignored). Токен / origin / порт берутся из общего ~/.bitrix24-mcp-bridge/config.json (через loadConfig) — дублировать их в .env не нужно, иначе dev-токен разойдётся с daemon. Осмысленно держать там лишь BITRIX_CATALOG (указывает dev-сборку/daemon на репозиторный actions.json). В проде весь конфиг — в ~/.bitrix24-mcp-bridge/config.json, который пишет setup.

Репо ≠ живой daemon. Daemon, к которому ходят агенты, читает runtime-папку (~/.bitrix24-mcp-bridge/actions.json + запущенный dist/cli.js), а не файлы репозитория. После правки каталога или кода сервера выполни bun run sync:runtime: она пересоберёт бандл, скопирует репо-actions.json в runtime-папку и погасит daemon (следующий вызов агента поднимет свежий). Без этого новые инструменты/методы агенту не видны.

Дистрибуция: bin bitrix24-bridge → dist/cli.js; npm-хук prepare при установке собирает и dist/cli.js, и статичные бандлы расширения (extension/dist/), которые setup затем копирует в runtime-домашнюю папку. Публикуемые файлы перечислены в files (dist, extension/dist, docs/api-notes.md, actions.example.json).

Релизы

Версионирование и публикация автоматизированы (conventional commits → release-please): бот ведёт release-PR с bump'ом версии и CHANGELOG.md; при его мерже создаётся GitHub Release/тег и пакет публикуется в npm через OIDC Trusted Publisher (с provenance, без токенов). CI (.github/workflows/ci.yml) гоняет typecheck + тесты на push/PR. Ручная до-публикация застрявшего релиза — workflow_dispatch на release-please.

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

• docs/RUNBOOK.md — установка, настройка, повседневная работа, диагностика

• docs/api-notes.md — карта API Bitrix24 для агента (единый источник для bitrix_help)

• docs/reconnaissance.md — capture, транспорт записи каталога, расширение actions.json

• extension/README.md — устройство расширения и модель доверия