Bitrix24 MCP Bridge

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

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

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

Полная инструкция — docs/RUNBOOK.md.

Коротко (первый запуск):

bun install && bun test
cp .env.example .env и заполнить: BITRIX_MCP_TOKEN (openssl rand -hex 32) и BITRIX_ORIGIN
Каталог методов: быстрый старт — cp actions.example.json actions.json (готовый рабочий каталог на все инструменты); свои методы — снять HAR, см. docs/reconnaissance.md
bun run build:ext (берёт конфиг из .env), загрузить папку extension/dist/ в Chrome (Load unpacked)
Зарегистрировать сервер у агента: claude mcp add bitrix24 -- bun --env-file=<abs>/.env run <abs>/src/index.ts
Проверить по docs/e2e-checklist.md

Вся конфигурация — в gitignored .env (единая точка правды для сервера и сборки расширения).

Последующие запуски: держать открытой залогиненную вкладку портала — сервер поднимает агент сам.

Инструменты

bitrix_tasks_list, bitrix_task_get, bitrix_projects_list, bitrix_chats_recent,bitrix_chat_messages, и универсальный bitrix_call для любого разрешённого вызова из каталога.

Разработка

bun test               # юнит-тесты (bun:test)
bun run typecheck      # tsc --noEmit (сервер + extension)
bun run build:ext      # собрать расширение (esbuild → extension/dist/)
bun run build:ext:capture  # capture-сборка (перехват вызовов для авто-разведки)
bun run capture        # рекордер: пишет actions.draft.json из перехваченных вызовов

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

docs/RUNBOOK.md — первый и последующие запуски, диагностика, безопасность
docs/api-notes.md — карта API Bitrix24 (транспорт, конвенции params, поля) — для любого агента
docs/reconnaissance.md — как снять HAR и собрать actions.json
docs/e2e-checklist.md — сквозная проверка

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

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

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

Read-only — это гарантия «доброй воли», а не защита. Ограничение на чтениепроверяется в MCP-сервере по имени метода из каталога (allowlist) и неинспектирует значения params. Недоверенный вызывающий, управляющий мостом,может обойти его. Не полагайтесь на read-only как на барьер против атакующего.
Любой локальный процесс считается доверенным. Кто угодно, кто может занятьloopback-порт или прочитать токен из .env / бандла расширения, способенуправлять мостом в объёме прав сессии (чтение и запись). Токен не являетсяграницей против локального атакующего — он лишь отсекает случайные подключения.
Токен читаем со страницы портала. Коннектор работает в MAIN-world вкладки;сторонний скрипт на странице портала (виджет маркетплейса, XSS) теоретическиможет перехватить токен и открыть собственный канал к мосту.

Вывод: запускайте только на доверенной машине, где вы контролируете вселокальные процессы; не используйте на общих или недоверенных хостах. Усилениеграницы (аутентификация пира внутри расширения, client-side allowlist,ISOLATED-world для токена) — известные открытые вопросы.

Bitrix24 MCP Bridge