Bitrix24 MCP Bridge

Мост между Claude (MCP) и Bitrix24 CRM/Задачами. Развёрнут на хостинге Beget по адресу mcp-bitrix.karpovpartners-it.ru.

1. Зачем это понадобилось

Изначально пытались подключить Claude к Bitrix24 через встроенный в Bitrix24 коннектор «МСР-подключения» (приложение aiassistant.bitrix_mcp / кнопка «Б24» в маркетплейсе). Оказалось, что эта функция не работает: эндпоинты /authorize, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource отдают голый nginx 404, хотя все настройки и подписка в порядке. Это баг/недокат фичи на стороне Bitrix24, а не ошибка в настройках.

В качестве обходного пути был написан собственный MCP-сервер («мост»), который:

• принимает MCP-запросы от Claude по протоколу Streamable HTTP;
• транслирует их в вызовы обычного REST API Bitrix24 через входящий вебхук (создан в Bitrix24 с правами только на CRM + Задачи);
• отдаёт результат обратно в Claude в виде MCP tool-ответов.

2. Архитектура и файлы

Файл	Назначение
server.mjs	Основной код моста (ES-модуль). Поднимает Express-сервер, разбирает MCP-запросы через @modelcontextprotocol/sdk, дергает REST API Bitrix24.
app.js	Тонкая CommonJS-обёртка для запуска server.mjs. Нужна из-за особенности Passenger на Beget (см. ниже).
package.json	Зависимости: @modelcontextprotocol/sdk, express, zod, undici.
.htaccess.example	Шаблон конфигурации Phusion Passenger + переменные окружения. Реальный .htaccess с боевыми секретами не хранится в репозитории (см. .gitignore) — он развёрнут напрямую на сервере и сохранён отдельно у владельца проекта.

Какие инструменты (tools) доступны в Claude

• bitrix24_call — вызов любого метода crm.*, task.*, tasks.*, user.current, profile напрямую (эскейп-люк).
• bitrix24_list_crm / bitrix24_get_crm / bitrix24_add_crm / bitrix24_update_crm — список/чтение/создание/обновление записей CRM (lead, deal, contact, company).
• bitrix24_list_tasks / bitrix24_add_task / bitrix24_update_task / bitrix24_complete_task — работа с задачами.

Сервер жёстко ограничивает вызываемые методы Bitrix24 префиксами crm., task., tasks., user.current, profile (см. ALLOWED_METHOD_PREFIXES в server.mjs) — это защита на случай, если у вебхука когда-нибудь появятся более широкие права.

3. Аутентификация / безопасность

У кастомных MCP-коннекторов в интерфейсе Claude нет поля для произвольных HTTP-заголовков — только URL (+ опционально OAuth Client ID/Secret). Поэтому вместо заголовка Authorization секрет зашит в путь URL:

https://mcp-bitrix.karpovpartners-it.ru/mcp/<секрет>

Секрет и адрес вебхука Bitrix24 хранятся только в боевом .htaccess на сервере и в приватной копии у владельца проекта — они намеренно не закоммичены в этот репозиторий (см. .gitignore). Любой, кто узнает секрет из URL, получит доступ к CRM и задачам Bitrix24 в рамках прав вебхука.

4. Как это работает по шагам

1. Claude открывает MCP-коннектор → POST на /mcp/<секрет> с телом {"method":"initialize", ...}.
2. Express-роут в server.mjs создаёт новый McpServer (StreamableHTTPServerTransport, sessionIdGenerator: undefined — сервер без сохранения сессии, каждый запрос независим).
3. Claude вызывает tools/list, затем tools/call с конкретным инструментом (например bitrix24_list_crm).
4. server.mjs вызывает bitrixCall(method, params), которая делает fetch() на https://<портал>.bitrix24.ru/rest/<id>/<вебхук>/<метод>.json.
5. Ответ Bitrix24 оборачивается в MCP-формат и уходит обратно в Claude.

5. Развёртывание с нуля

1. Создать входящий вебхук в Bitrix24: Настройки → Разработчикам → Другое → Входящий вебхук. Права — минимум CRM + Задачи.
2. Склонировать репозиторий на сервер, в директорию сайта (public_html вашего домена/поддомена).
3. npm install в этой директории (поставит express, zod, @modelcontextprotocol/sdk, undici).
4. Скопировать .htaccess.example в .htaccess и прописать реальные BITRIX_WEBHOOK_URL и MCP_PATH_SECRET.
5. На Beget: mkdir tmp && touch tmp/restart.txt — команда Passenger на перезапуск приложения после любых изменений в коде.
6. В панели Beget: «Сайты» → у нужного сайта → «⋮» → «Прикрепить домен» — без этого шага Apache даже не пытается достучаться до вашего кода (см. раздел 6.2 — легко забыть, ошибка неочевидная).

6. Проблемы, с которыми столкнулись при разворачивании на Beget, и как их решили

Журнал отладки — пригодится при повторном развёртывании на Beget или другом shared-хостинге со старым Node.js.

6.1. Node.js на Beget — версия 16.20.2, слишком старая

На стороне Beget (Ubuntu 18.04, glibc 2.27) официальные сборки Node 18+ не запускаются (GLIBC_2.28' not found). Пришлось остаться на Node 16.20.2 и вручную подложить недостающие в Node 16 глобальные объекты, которые нужны современным зависимостям (@modelcontextprotocol/sdk, Express 5):

• fetch, Headers, Request, Response — через пакет undici.
• crypto (Web Crypto API, crypto.randomUUID()) — через встроенный node:crypto (webcrypto).
• ReadableStream, WritableStream, TransformStream — через встроенный node:stream/web.
• structuredClone, MessageChannel/MessagePort — на всякий случай, через node:v8 и node:worker_threads.

Всё это — в самом начале server.mjs, до импорта Express и MCP SDK (сделано через await import(...), а не через обычный import сверху файла — см. следующий пункт, почему).

6.2. Домен не был «приклеен» к папке сайта

После загрузки кода на сервер сайт отдавал фирменную страницу Beget «Домен не привязан к директории на сервере» вместо приложения. Просто создать папку сайта и залить туда файлы недостаточно — домен нужно отдельно «прикрепить» через панель: Сайты → нужный сайт → ⋮ → «Прикрепить домен». Неочевидный шаг, который легко пропустить.

6.3. ERR_REQUIRE_ESM: Passenger не умеет грузить ES-модули

Passenger на Beget (старая версия, passenger40) запускает стартовый файл через require(), а require() в Node принципиально не умеет грузить ES-модули (import/export, type: module в package.json). server.mjs использует await на верхнем уровне файла — а это возможно только в ES-модуле.

Решение: в package.json нет "type": "module" (по умолчанию .js — CommonJS), сам код лежит в файле с расширением .mjs (расширение .mjs — это всегда ES-модуль, вне зависимости от package.json), а точкой входа для Passenger сделан app.js — крошечный CommonJS-файл:

// app.js
import('./server.mjs').catch((err) => {
  console.error('Failed to start server:', err);
  process.exit(1);
});

require() спокойно загружает app.js (это обычный CommonJS), а внутри него динамический import() (это функция, а не декларация) уже может асинхронно загрузить ES-модуль server.mjs.

6.4. Секрет в пути URL

MCP_PATH_SECRET — случайная строка (например, secrets.token_urlsafe(32) в Python, или crypto.randomUUID() + crypto.randomUUID() в консоли браузера). Если нужно перевыпустить секрет — сгенерировать новый и обновить в .htaccess на сервере и в настройках коннектора в Claude.

7. Как подключить в Claude

1. claude.ai → Настройки → Connectors → Add custom connector.
2. Name: Bitrix24 (любое).
3. Remote MCP server URL: https://mcp-bitrix.karpovpartners-it.ru/mcp/<секрет>
4. OAuth Client ID / Secret — оставить пустыми, они не нужны (авторизация уже зашита в URL).
5. Сохранить, включить коннектор в чате.

8. Открытый вопрос — родной MCP-коннектор Bitrix24

Стоит написать в поддержку Bitrix24 про сломанный нативный MCP-коннектор («Б24» в маркетплейсе): /authorize и стандартные OAuth-discovery эндпоинты отдают голый nginx 404 при включённых настройках и активной подписке. Когда/если Bitrix24 это починит, можно будет переключиться на официальный коннектор — либо оставить этот мост, он тоже рабочий и даёт больше контроля (например, ограничение методов до CRM+Задачи прямо в коде).