Bitrix24 Tasks, CRM & Lists MCP Server

Типизированный MCP-сервер для Bitrix24 на Node.js/TypeScript. Даёт Claude (или любому другому MCP-клиенту) 46 инструментов для работы с задачами и проектами (воркгруппами/канбаном), CRM (сделки, контакты, пользователи, активности) и Списками (Универсальные списки) через стандартный входящий webhook Bitrix24 REST API — без сторонних кастомных модулей.

Bitrix24 — единственный источник истины: сервер ничего не кеширует и не хранит производных копий бизнес-данных.

Архитектура

Claude/Cursor -> Docker MCP stdio -> Bitrix24 REST v2/v3

Опционально — второй, HTTP-транспорт с мультиаккаунтным OAuth-логином (для claude.ai Team/браузер-коннекторов), backed небольшой Postgres-таблицей аккаунтов:

claude.ai -> HTTP + OAuth -> Bitrix24 REST v2/v3
                    |
                    +-> PostgreSQL (только таблица аккаунтов)

Подробности: архитектура, модули, права доступа, развёртывание, операции, удалённый доступ, ручное тестирование, примеры промптов.

Related MCP server: BitrixMCP

Модули

Сервер устроен как ядро + подключаемые модули по доменам (tasks, crm, lists) — каждый модуль можно отключить (MCP_ENABLED_MODULES), а свой (в том числе полностью сторонний, вне этого репозитория) — подключить через MCP_EXTRA_MODULES. Полный контракт модуля и как написать свой — docs/modules.md.

Требования

• Docker Engine / Docker Desktop с Docker Compose v2;

• существующий портал Bitrix24;

• входящий webhook с нужными scope (task, crm, при необходимости calendar, im, timeman, user, lists);

• PostgreSQL нужен только для мультиаккаунтного HTTP-транспорта — обычный stdio-запуск с одним общим вебхуком работает вообще без базы.

Node.js/npm на хост устанавливать не нужно — все команды выполняются в Docker. Для локальной разработки без Docker достаточно Node.js ≥20.

Быстрый запуск

1. Скопируйте .env.example в .env, заполните BITRIX_WEBHOOK_BASE.

2. Проверьте, что .env не попадает в Git (.gitignore уже это делает).

3. Запустите MCP через stdio:

docker compose build
docker compose run --rm -T mcp

Для Cursor/Claude Desktop проектный .mcp.json запускает ту же команду. stdout зарезервирован для MCP-протокола; структурированные логи идут в stderr.

Без Docker (локальная разработка):

npm install
npm run dev

Переменные окружения

Bitrix24

• BITRIX_WEBHOOK_BASE — секретный URL вида https://portal.example.ru/rest/123/token. Не коммитьте и не выводите в лог.

• BITRIX_DEFAULT_DEAL_CATEGORY — имя CRM-воронки по умолчанию.

• BITRIX_DEFAULT_GROUP_ID — ID проекта/группы, используемый task-инструментами, когда пользователь не указал проект явно. Пустое/неположительное/нечисловое значение игнорируется.

• BITRIX_REPO_GROUP_MAP — JSON-объект {"owner/repository":172}, сопоставляющий имя репозитория с ID Bitrix24-проекта; ключи нормализуются в lower-case, некорректный JSON даёт пустую карту.

Модули (см. docs/modules.md)

• MCP_ENABLED_MODULES — список id встроенных модулей через запятую (tasks, crm, lists). Не задано — включены все; пустая строка отключает все встроенные (останется только bitrix_test_connection).

• MCP_EXTRA_MODULES — сторонние модули вне репозитория: npm-пакеты и/или пути к файлам через запятую. Регистрируются всегда, если успешно загрузились, независимо от MCP_ENABLED_MODULES. Выполняет произвольный код с правами процесса — указывайте только то, чему доверяете.

PostgreSQL (только для мультиаккаунтного HTTP-транспорта)

• DATABASE_URL, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD.

Удалённый HTTP-транспорт (опционально)

• MCP_TRANSPORT — stdio (по умолчанию) или http. Влияет только на сервис mcp-http в docker-compose.

• MCP_HTTP_PORT — порт HTTP-сервера, по умолчанию 3000.

• MCP_PUBLIC_URL — внешний HTTPS-адрес сервера (адрес туннеля при тесте, домен при постоянном хостинге); используется как OAuth issuer.

• Каждый аккаунт (логин + пароль + свой личный Bitrix-вебхук + роль) создаётся и управляется командой npm run manage-accounts (см. docs/access-control.md). MCP_AUTH_USERNAME/MCP_AUTH_PASSWORD_HASH — только одноразовый bootstrap: если mcp_accounts пуста при старте, из них и BITRIX_WEBHOOK_BASE заводится один аккаунт с ролью admin.

• MCP_TOKEN_TTL_SECONDS, MCP_REFRESH_TOKEN_TTL_SECONDS — время жизни access/refresh токенов.

Подробный пошаговый запуск (включая тест через ngrok/Cloudflare Tunnel и подключение из claude.ai): docs/remote-access.md.

MCP-инструменты — 46

По умолчанию, при всех включённых встроенных модулях — см. Модули выше. Если отключить часть через MCP_ENABLED_MODULES, инструментов будет меньше.

Полный список с примерами вызова — docs/manual-testing.md.

Задачи и проекты — 26

connection · list/get/history/messages/checklist/result · update · create/start/complete · move stage · project stages (list/create) · projects (list/create/members: list/add/remove/update-role) · calendar (find-slot/schedule-meeting) · timesheet · worktime report · send-direct-message.

CRM — 18

сделки (categories/stages/list/get/create/update/move/comment) · контакты (list/get/find/create/update) · пользователи (list/get) · активности (list/create).

Списки (Lists) — 2

bitrix_lists_search_letters, bitrix_lists_get_letter_file — поиск и скачивание вложений в реестре входящей/исходящей корреспонденции (Универсальные списки). Требует настройки под ваш портал — см. docs/manual-testing.md.

Все write-инструменты требуют confirm=true. Универсального REST-инструмента нет — каждый tool валидирует и ограничивает набор полей отдельно.

Тесты и качество

docker compose --profile test run --rm test
docker compose --profile test down --volumes

Локально:

npm run check   # typecheck + lint + format:check + test + build

Bitrix integration smoke (tests/integration) запускается только при RUN_BITRIX_INTEGRATION_TESTS=true, запись — только при дополнительном подтверждении. По умолчанию реальные записи никогда не выполняются.

Backup и восстановление (мультиаккаунтный HTTP-транспорт)

docker compose exec -T postgres pg_dump -U bitrix_mcp -d bitrix_mcp -Fc > bitrix-mcp.backup

Актуально только если используется mcp-http — таблица mcp_accounts хранит логины/роли/личные вебхуки аккаунтов. Для обычного stdio-запуска с одним вебхуком базы нет и бэкапить нечего.

Ограничения

• удалённый HTTP-транспорт (mcp-http) хранит OAuth-клиентов и токены в памяти процесса (не переживает рестарт контейнера); аккаунты (логин/пароль/роль/вебхук) хранятся в Postgres и рестарт переживают — см. docs/remote-access.md.

• роль аккаунта (developer/business_analyst/product_owner/admin) — описательное поле, ничем не гейтится "из коробки" — см. docs/access-control.md.

• нет универсального REST passthrough-инструмента — каждый tool сознательно ограничивает набор полей, которые можно менять.