Bitrix24 MCP Bridge

Локальный MCP-сервер, дающий ИИ-агенту read-only доступ к задачам, проектам и чатам 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] выход.

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

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

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

Инструменты

Все — read-only, каждый принимает необязательный параметр portal (alias; по умолчанию — портал по умолчанию из config.json):

| Инструмент | Назначение | |---|---| | bitrix_help | справка по API/params (то же, что docs/api-notes.md) | | bitrix_status | какие порталы сконфигурированы и какие сейчас подключены | | bitrix_call | любой разрешённый вызов из каталога по имени | | bitrix_tasks_list / bitrix_task_get | задачи | | bitrix_projects_list / bitrix_project_get | рабочие группы / проекты | | bitrix_chats_recent / bitrix_chat_messages | чаты и история сообщений |

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 — физически в расширении, а не в сервере. Отсюда:

• Read-only — гарантия «доброй воли», а не защита. Ограничение на чтение — это denylist мутирующих глаголов (…add/…update/…delete/…) в каталоге; каталог с мутирующим вызовом просто не загрузится. Значения params при этом не инспектируются.
• Токен — единственная защита 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:ext               # dev-сборка пер-пользовательского расширения

.env — только dev-оверрайд (gitignored): BITRIX_MCP_TOKEN, BITRIX_ORIGIN, BITRIX_MCP_PORT, опционально BITRIX_CATALOG. В проде конфиг живёт в ~/.bitrix24-mcp-bridge/config.json, который пишет setup.

Дистрибуция: 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).

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

• docs/RUNBOOK.md — установка, настройка, повседневная работа, диагностика
• docs/api-notes.md — карта API Bitrix24 (единый источник для bitrix_help)
• docs/reconnaissance.md — как снять HAR и расширить actions.json
• extension/README.md — устройство расширения и модель доверия