Skip to main content
Glama
Sign In
Bitrix24 Tasks, CRM & Lists MCP Server

Bitrix24 Tasks, CRM & Lists MCP Server

by CIA-Les
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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 сознательно ограничивает набор полей, которые можно менять.

Available Tools

46 tools
bitrix_add_deal_commentA

Добавить комментарий в timeline сделки. Требует confirm=true.

Inputs: text (required), dealId (required), confirm (required).

bitrix_add_project_membersA

Добавить участников в уже существующий проект (воркгруппу) Bitrix24 — без похода в интерфейс. Требует confirm=true.

Inputs: confirm (required), userIds (required), role, groupId, +1 more.

bitrix_add_task_messageC

Отправить сообщение в чат задачи Bitrix24. Требует confirm=true.

Inputs: text (required), taskId (required), confirm (required).

bitrix_attach_task_resultC

Зафиксировать результат работы по задаче (tasks.task.result.add). Требует confirm=true.

Inputs: text (required), taskId (required), confirm (required).

bitrix_complete_taskB

Завершить задачу (tasks.task.complete). Требует confirm=true.

Inputs: taskId (required), confirm (required).

bitrix_create_activityA

Создать дело (звонок, встречу или задачу) в CRM. Требует confirm=true. Укажите dealId или contactId.

Inputs: type (required), confirm (required), subject (required), dealId, +5 more.

bitrix_create_contactA

Создать контакт в Bitrix24 CRM. Требует confirm=true.

Inputs: name (required), confirm (required), email, phone, +4 more.

bitrix_create_dealB

Создать сделку в Bitrix24 CRM. Требует confirm=true.

Inputs: title (required), confirm (required), category, comments, +5 more.

bitrix_create_projectA

Создать новый проект (воркгруппу) Bitrix24 — тот же раздел, что .../tasks/projects/. Требует confirm=true.

Inputs: title (required), confirm (required), opened, visible, +2 more.

bitrix_create_project_stageB

Создать новую колонку канбана (доску) в проекте. Требует confirm=true.

Inputs: name (required), confirm (required), projectId (required), sortOrder.

bitrix_create_taskA

Создать новую задачу, в проекте или свободную (без привязки к проекту, если projectId не указан). responsibleId обязателен — Bitrix24 отклоняет задачу без исполнителя, с проектом или без. Требует confirm=true.

Inputs: title (required), confirm (required), responsibleId (required), stageId, +3 more.

bitrix_find_contactA

Найти контакт по телефону и/или email (crm.duplicate.findbycomm).

Inputs: email, phone.

bitrix_find_free_slotA

Найти общий свободный слот в календаре для нескольких участников (read-only, ничего не создаёт). Возвращает до maxCandidates слотов в формате "DD.MM.YYYY HH:MM:SS" — тот же формат принимает bitrix_schedule_meeting в полях from/to. Требует область доступа "calendar" у вебхука.

Inputs: windowTo (required), windowFrom (required), participantIds (required), durationMinutes (required), +3 more.

bitrix_get_contactA

Получить полную информацию о контакте Bitrix24 по ID.

Inputs: contactId (required).

bitrix_get_dealA

Получить полную информацию о сделке Bitrix24 по ID.

Inputs: dealId (required).

bitrix_get_taskB

Получить полную информацию о задаче Bitrix24 по ID.

Inputs: taskId (required).

bitrix_get_task_checklistA

Получить чек-лист задачи Bitrix24 как критерии приёмки.

Inputs: taskId (required).

bitrix_get_task_historyC

Получить историю изменений задачи Bitrix24.

Inputs: taskId (required), limit.

bitrix_get_timesheet_summaryA

Сводка учёта рабочего времени по задачам (read-only): суммарные часы по пользователям и, внутри каждого пользователя, по задачам, за период dateFrom..dateTo. Можно ограничить конкретными пользователями и/или проектом. Требует область доступа "tasks" (уже есть) — timeman.status-часть сводки (только при заданных userIds) требует ещё и "timeman".

Inputs: dateTo (required), dateFrom (required), userIds, projectId.

bitrix_get_userB

Получить полную информацию о пользователе Bitrix24 по ID.

Inputs: userId (required).

bitrix_get_worktime_reportA

Сводка учёта РАБОЧЕГО ДНЯ (read-only, модуль timeman.api.worktimerecord — тот же, что стоит за виджетом "День завершён HH:MM:SS" в карточке профиля): часы, простой (idle) и количество отработанных дней по пользователям за период dateFrom..dateTo. Не путать с bitrix_get_timesheet_summary — та сводка про время, списанное на задачи (task.elapseditem), эта — про фактическое открытие/закрытие рабочего дня. Область охвата — departmentId (сотрудники отдела) и/или явный userIds; нужен хотя бы один из них. Требует область доступа "timeman".

Inputs: dateTo (required), dateFrom (required), userIds, departmentId.

bitrix_list_activitiesB

Список дел (активностей) по сделке или контакту.

Inputs: limit, dealId, contactId.

bitrix_list_contactsC

Список контактов Bitrix24 CRM с поиском по имени.

Inputs: limit, order, search, assignedId.

bitrix_list_deal_categoriesB

Список воронок сделок Bitrix24 CRM.

Inputs: no named parameters.

bitrix_list_deal_commentsC

Список комментариев timeline сделки Bitrix24.

Inputs: dealId (required), limit.

bitrix_list_dealsB

Список сделок Bitrix24. Указывайте category (воронка) и stages (стадии) по названию.

Inputs: limit, order, search, stages, +4 more.

bitrix_list_deal_stagesB

Список стадий воронки сделок по названию category. ID не нужны.

Inputs: category, categoryId.

bitrix_list_project_membersA

Список участников проекта (воркгруппы) Bitrix24 — ID, роль, имя.

Inputs: groupId, project.

bitrix_list_projectsA

Список доступных проектов Bitrix24 по названию.

Inputs: project.

bitrix_list_project_stagesB

Список колонок канбана проекта по названию. ID не нужны.

Inputs: project.

bitrix_lists_get_letter_fileA

Скачать содержимое одного вложения письма из реестра «Списки» по attachedObjectId, полученному из bitrix_lists_search_letters. Возвращает содержимое файла в base64.

Inputs: direction (required), attachedObjectId (required).

bitrix_lists_search_lettersA

Найти письма в реестре Bitrix «Списки» (входящие/исходящие) по проекту, теме или номеру письма. projectQuery ищет подстрокой в «Реестре проектов» и ограничивает выборку найденными проектами; letterNumber ищет по подстроке «№<номер>» в названии письма (устойчиво к тому, что поле номера менялось со временем); query — свободный текстовый поиск по теме письма. Каждый результат содержит files — ссылки на вложения (propertyCode + attachedObjectId), которые передаются в bitrix_lists_get_letter_file для скачивания. Не поддерживает часть устаревших файловых полей исходящих писем (CFile-based, не Disk) — см. NEXT_AGENT_PROMPT.md.

Inputs: direction (required), limit, query, letterNumber, +1 more.

bitrix_list_task_messagesC

Получить сообщения и комментарии задачи Bitrix24.

Inputs: taskId (required), limit.

bitrix_list_tasksB

Список задач Bitrix24. Указывайте project (название) и stages (колонки канбана). ID не нужны.

Inputs: limit, order, search, stages, +3 more.

bitrix_list_usersC

Поиск и список сотрудников Bitrix24 по имени, фамилии или email.

Inputs: limit, order, search, activeOnly.

bitrix_move_deal_stageA

Переместить сделку в стадию воронки по названию. Требует confirm=true.

Inputs: dealId (required), confirm (required), stageName (required), category.

bitrix_move_task_stageA

Переместить задачу в колонку канбана по названию. Требует confirm=true.

Inputs: taskId (required), confirm (required), stageName (required).

bitrix_remove_project_membersB

Удалить участников из проекта (воркгруппы) Bitrix24. Требует confirm=true.

Inputs: confirm (required), userIds (required), groupId, project.

bitrix_schedule_meetingA

Создать полноценную встречу в календаре Bitrix24 с приглашением участников (они получат уведомление, и встреча покажется как занятость в их календаре). from/to — в формате "DD.MM.YYYY HH:MM:SS", как в ответе bitrix_find_free_slot. Организатором становится владелец вебхука. Требует confirm=true и область доступа "calendar" у вебхука.

Inputs: to (required), from (required), title (required), confirm (required), +2 more.

bitrix_send_direct_messageA

Отправить личное сообщение пользователю Bitrix24 или в существующий чат/диалог по dialogId (не сообщение в чат задачи — для этого используйте bitrix_add_task_message). Требует confirm=true. Требует, чтобы у входящего вебхука была включена область доступа "im" — если это не так, инструмент вернёт понятную ошибку с инструкцией, а не сырую ошибку Bitrix.

Inputs: text (required), confirm (required), userId, dialogId.

bitrix_start_taskA

Перевести задачу в статус «Выполняется» (tasks.task.start). Требует confirm=true.

Inputs: taskId (required), confirm (required).

bitrix_test_connectionA

Проверить соединение с Bitrix24 через входящий вебхук и доступность REST API задач и CRM.

Inputs: no named parameters.

bitrix_update_contactB

Изменить ограниченный набор полей контакта (NAME, LAST_NAME, PHONE, EMAIL, COMMENTS). Требует confirm=true.

Inputs: fields (required), confirm (required), contactId (required).

bitrix_update_dealA

Изменить ограниченный набор полей сделки (TITLE, COMMENTS, OPPORTUNITY, CURRENCY_ID). Требует confirm=true.

Inputs: dealId (required), fields (required), confirm (required).

bitrix_update_project_member_roleA

Изменить роль существующего участника проекта (воркгруппы) Bitrix24. Требует confirm=true.

Inputs: role (required), userId (required), confirm (required), groupId, +1 more.

bitrix_update_taskA

Безопасно изменить ограниченный набор полей задачи (TITLE, DESCRIPTION, DEADLINE, PRIORITY). Требует confirm=true.

Inputs: fields (required), taskId (required), confirm (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.2/5.0

    Scored across 46 tools

    Disambiguation4/5

    Most tools are clearly separated by resource and action (tasks, deals, contacts, users, projects, calendar, Lists). The main boundary risks are bitrix_create_activity overlapping semantically with bitrix_schedule_meeting and bitrix_create_task, but the descriptions clarify the module context well.

    Naming Consistency4/5

    The bitrix_ prefix with snake_case verb_noun naming is consistent throughout, e.g. bitrix_list_tasks, bitrix_get_task, bitrix_create_deal. Minor deviations like bitrix_lists_search_letters and bitrix_find_contact are still readable and do not break the overall pattern.

    Tool Count2/5

    With 46 tools, the server exceeds the 25+ threshold and feels heavy even though it covers three domains. The large surface creates selection overhead and could be better scoped or split into separate servers.

    Completeness3/5

    Core create/read/update flows exist for tasks, deals, contacts, and projects, plus useful extras like calendar scheduling and time reports. However, there are no delete or archive tools for any entity, activities lack update/delete, and meetings cannot be updated or cancelled.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • fast-bitrix24-mcp

      darkClaw921
      F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for interacting with Bitrix24 REST API, enabling CRUD operations on deals, contacts, companies, users, leads, and tasks, plus analytics and risk assessment.
      2
      -

    • BitrixMCP

      john7ross
      A
      license
      B
      quality
      C
      maintenance
      Universal MCP server for the Bitrix24 REST API, enabling full read and write access to CRM, tasks, calendar, disk, and more. Supports any MCP client with stdio or Streamable HTTP transport.
      88
      1
      MIT

    • bitrix24-mcp

      RCS-kz
      F
      license
      Not graded
      quality
      C
      maintenance
      Production-grade MCP server for Bitrix24 Cloud with 45 tools, safe by default. Connects Claude Desktop to your Bitrix24 tenant for AI-driven CRM, tasks, messaging, and calendar operations.
      -

    • bitrix24-mcp

      imejaikin
      A
      license
      B
      quality
      C
      maintenance
      MCP server that gives AI assistants direct access to Bitrix24 portal through an inbound webhook, enabling management of tasks, kanban boards, reports, chats, files, and knowledge base.
      48
      MIT