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 + расширение
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 и материализует расширение в ~/.bitrix24-mcp-bridge/extension/ (статичные JS-бандлы + config.json + manifest.json, собранный под ваши порталы).

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

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

• Daemon — MCP-клиент новой версии при старте сверяет версию работающего daemon и, если она старше, гасит его и поднимает свой (в stderr — [mcp] restarted daemon <старая> → <новая>). Более новый daemon клиент не трогает ([mcp] daemon <v> is newer than this client <v>; leaving it), чтобы две установленные версии не перезапускали daemon друг у друга по очереди.

• Устаревшие файлы — actions.json и catalog-state.json от прежней модели (каталог вызовов) удаляются из ~/.bitrix24-mcp-bridge/ при старте ([cleanup] removed …). config.json и downloads/ не трогаются никогда.

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

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

Переход на встроенные операции — несовместимый (breaking) релиз. bitrix_call и пользовательский каталог вызовов убраны; агент работает только через инструменты из таблицы ниже. Первый же MCP-клиент новой версии заменит daemon, и клиенты, запущенные прежней версией (другие открытые сессии агентов), потеряют мост — на вызовы они получат unsupported request type call — this daemon is <версия>; restart the agent session…; им нужно перезапустить сессию агента.

Мультипортальность поддержана: каждый портал — отдельная запись, а в манифесте расширения 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: b24-mcp

Инструменты

Кроме bitrix_help / bitrix_status, каждый инструмент — встроенная операция моста (src/ops/): типизированные аргументы, разумные дефолты, запрос к Bitrix24 строит и проверяет daemon. Набор операций фиксирован в коде; произвольного вызова Bitrix-метода по имени нет. У большинства операций (пометка «+ params» в docs/api-notes.md §3) есть необязательный params в нативном формате Bitrix (мержится последним, перекрывает дефолты). Каждый инструмент принимает необязательный portal (alias; по умолчанию — из config.json). Мутирующие помечены ⚠: они включены по умолчанию и выключаются одним переключателем (см. «Переключатель мутаций»). Мутирующие операции, кроме отметки прочитанным (bitrix_chat_mark_read / bitrix_chat_read_all), не принимают params; изменения задач они, где это возможно, перечитывают после записи, а списочные поля (соисполнители, наблюдатели, теги) правят поверх текущего значения задачи.

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

Переключатель мутаций

Мутирующие операции — все помеченные ⚠ в таблице выше (полный список — bitrix_help / docs/api-notes.md §3, «Мутирующие операции») — по умолчанию разрешены. Они действуют от имени пользователя: другие участники видят изменения и получают уведомления Bitrix24 (кто именно — там же). Запретить их можно тремя способами (побеждает верхний):

1. env BITRIX_MCP_MUTATIONS=off (или on) у процесса daemon;

2. "mutations": false в ~/.bitrix24-mcp-bridge/config.json;

3. setup → [m] — переключает то же поле и перезапускает daemon; открытые сессии агентов переподключаются к новому daemon сами на следующем вызове.

Текущее состояние видно в bitrix_status (поле mutations). Политику применяет daemon: запрещённая операция не уходит в Bitrix24, агент получает ошибку operation <имя> changes data, but mutations are disabled…. Операции чтения переключатель не трогает.

Скачивание файлов

bitrix_file_download принимает только ссылки на файлы сконфигурированного портала — иначе произвольный URL стал бы аутентифицированным GET к любому эндпоинту портала. Разрешены:

• /bitrix/services/main/ajax.php с action = disk.api.file.download, disk.attachedObject.download или call.Track.download;

• /bitrix/tools/disk/uf.php с action = download, show или downloadArchiveByEntity.

Повторённый (action=…&action=…) или массивный (action[]=…) action отклоняется: PHP читает другое значение, чем проверка. Файлы ложатся в ~/.bitrix24-mcp-bridge/downloads/; мост их не удаляет. Когда файлы папки в сумме больше 500 МБ, напоминание почистить её (warning) приходит в ответах операций, записавших файл в эту папку, — bitrix_file_download, bitrix_call_recording, bitrix_call_detail и bitrix_task_comments (последние две — когда сохранили файл), — и в bitrix_status.

Известное ограничение: другие формы ссылок портала на файлы (например, /disk/downloadFile/… из интерфейса Диска или публичные /docs/pub/…) отклоняются — бери ссылку из ответа моста.

Архитектура

Модель — один долгоживущий 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, bridge.sock, extension/, downloads/.

Разрешение настроек слоями (побеждает верхний): env → .env (только для разработки) → ~/.bitrix24-mcp-bridge/config.json. Ключи config.json: token, port, portals, defaultPortal, mutations (см. «Переключатель мутаций»).

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

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

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

• Граница — набор встроенных операций и переключатель мутаций. Мост выполняет только операции из src/ops/; запрос к Bitrix24 строит daemon, произвольный метод по имени вызвать нельзя. Значения params не инспектируются — агент управляет выборкой в рамках этого метода; отклоняются только ключи action, c, mode, sessid (и их […]-формы): они выбирают контроллер или несут CSRF-токен, и их задаёт сама операция. Мутирующие операции выполняются, пока не выключены ("mutations": false). Общий локальный токен (риск G7) означает: процесс, знающий токен и порт демона, может выполнять эти операции в объёме прав пользователя.

• Скачивание — только ссылки на файлы портала (allowlist путей и action, см. «Скачивание файлов»): bitrix_file_download не превращается в произвольный GET.

• Токен — единственная защита 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:static        # статичные бандлы расширения → extension/dist/
bun run sync:runtime            # применить репо-изменения к живому daemon и расширению (см. ниже)

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

Репо ≠ живой daemon. Daemon, к которому ходят агенты, исполняет собранный dist/cli.js, а не исходники репозитория. После правки кода сервера (операции в src/ops/, регистрация инструментов) или расширения (extension/src/) выполни bun run sync:runtime: она пересоберёт бандл и статичные бандлы расширения, обновит расширение, развёрнутое setup в ~/.bitrix24-mcp-bridge/extension/ (если его там нет — пропустит), и погасит daemon (следующий вызов агента поднимет свежий). Затем перезагрузи расширение на chrome://extensions и вкладку портала. Без этого новые операции агенту не видны. Как добавить операцию — docs/reconnaissance.md.

Запуск из исходников (bun run src/index.ts) не знает своей версии, поэтому не заменяет daemon другой версии и не чистит устаревшие файлы — это делает только собранный dist/cli.js, чтобы dev-запуск не трогал установленный мост.

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

Релизы

Версионирование и публикация автоматизированы (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 — справка по инструментам для агента (единый источник для bitrix_help)

• docs/reconnaissance.md — для мейнтейнера: как добавить операцию, транспорт, Bitrix-методы операций

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