bitrix24-local-mcp

MCP-сервер для Bitrix24. Даёт AI-ассистентам (Claude, Cursor и др.) прямой доступ к вашему порталу Bitrix24 через входящий вебхук: задачи и канбан, отчёты и аналитика загрузки, чаты и мессенджер, файлы, база знаний, пользователи. ~40 инструментов, один файл, без облака — сервер ходит в Bitrix напрямую с вашей машины.

An MCP server for Bitrix24 — lets AI assistants manage tasks, kanban boards, reports, chats, files and the knowledge base of your Bitrix24 portal through an inbound webhook.

Bitrix24 — самая распространённая CRM/таск-система в РФ и СНГ. Этот сервер превращает её в инструмент, которым пользуется AI-агент: «покажи мои задачи в работе», «собери отчёт по проекту за неделю», «кто перегружен», «заархивируй завершённые».

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

1. Получить вебхук в Bitrix24. Приложения → Разработчикам → Входящий вебхук (в некоторых версиях: Приложения → Вебхуки → Входящий вебхук). Отметьте права Задачи и проекты (task), Мессенджер (im), Диск (disk), Пользователи (user), Рабочие группы (sonet_group) — полный разбор скоупов ниже. Скопируйте URL, он выглядит так:

https://ВАШ-ПОРТАЛ.bitrix24.ru/rest/USER_ID/СЕКРЕТНЫЙ_КОД/

2. Установить и настроить.

git clone <URL репозитория>
cd bitrix24-local-mcp
npm install
cp .env.example .env
# вписать свой BITRIX24_WEBHOOK_URL в .env

3. Подключить к AI-клиенту (Claude Code / Cursor) — см. раздел «Подключение» ниже.

⚠️ Вебхук = полный доступ к порталу под правами его владельца. Храните его как пароль: он в .env, который под .gitignore и в репозиторий не попадает.

Related MCP server: bitrix24-mcp-server

Инструменты

Задачи

Мессенджер

Треды доступны через im.v2.Chat.Message.*, хотя эти методы не публикуются в REST-манифесте webhook. Если im.v2.* станет недоступен, im_chat_messages продолжит работать без поля thread, а im_thread_messages попробует существующий fallback im_message_comments.

Файлы

Пользователи

База знаний

Универсальный

Установка

git clone <URL репозитория>
cd bitrix24-local-mcp
npm install
cp .env.example .env
# Заполнить BITRIX24_WEBHOOK_URL в .env

Настройка webhook в Bitrix24

1. Перейти в Приложения → Вебхуки → Входящий вебхук

2. Создать вебхук с правами (минимальный набор для работы инструментов):

   • task — Задачи и проекты. Обязательно, на нём держится почти весь сервер: списки/создание/обновление задач, комментарии, канбан, архив, брифы проектов. Чекбокс «Задачи и проекты» в Bitrix выдаёт связку task / tasks / tasks_extended. ⚠️ Именно task (в единственном числе) нужен методам tasks.task.*, task.stages.*, task.commentitem.* — одного tasks недостаточно.

   • im — Мессенджер: чаты задач, поиск чатов, отправка файлов в диалоги.

   • disk — Диск: загрузка и прикрепление файлов.

   • user — Пользователи: tasks_my, поиск/резолв пользователей.

   • sonet_group — Рабочие группы (Социальная сеть): проектные/групповые инструменты (sonet_group.get).

   • landing — Лендинги: инструменты базы знаний (этап H). Можно не включать, пока инструменты kb_* не используются.

   • note — База знаний 2.0: инструменты kb2_* для документов /note/document/.... Для чтения нужно право «Просмотр», для kb2_document_create — право создания в нужной базе/родителе, для kb2_document_update — право «Редактирование» конкретного документа или базы, для kb2_document_delete — право удаления документа. Scope добавляется к webhook вручную; после сохранения ещё раз проверьте остальные отмеченные права.

   • calendar — Календарь: выделенных инструментов в сервере нет, но методы calendar.event.*/calendar.section.* дёргаются через bitrix_call (утренний бриф, создание встреч). Без этого права такие вызовы падают с 401/insufficient_scope.

3. Скопировать URL вебхука в .env

Права проверены против живого API. При ручном редактировании прав вебхука в UI Bitrix следите, чтобы не сбросить ранее выданные скоупы: интерфейс может оставить только что отмеченные права. Если задачи перестали работать с insufficient_scope — вернулось ли право task (Задачи и проекты).

Подключение к Claude Code

В файле ~/.claude/settings.json или .claude/settings.json проекта:

{
  "mcpServers": {
    "bitrix24-local": {
      "command": "node",
      "args": ["/path/to/bitrix24-local-mcp/index.js"]
    }
  }
}

Подключение к Cursor

В файле .cursor/mcp.json проекта:

{
  "mcpServers": {
    "bitrix24-local": {
      "command": "node",
      "args": ["/path/to/bitrix24-local-mcp/index.js"]
    }
  }
}

Примеры использования

Мои задачи

tasks_my
tasks_my filter={"!STATUS": 5} order={"DEADLINE": "asc"}
tasks_my user_id=45

Объединяет задачи, где пользователь — исполнитель и постановщик (с дедупом). Если user_id не указан — определяется через user.current. Каждая задача содержит поле _role: ["responsible"] / ["creator"] / ["responsible", "creator"].

Фильтрация задач

tasks_list filter={"RESPONSIBLE_ID": 45, "!STATUS": 5}

DESCRIPTION нельзя передавать в tasks_list filter: Bitrix24 на проверенном портале молча игнорирует такой фильтр. Инструмент вернёт явную ошибку вместо неотфильтрованной выдачи.

Поиск текста в задачах

tasks_search_text query="figma" group_id=9
tasks_search_text query="Pet in Vet" from="2026-01-01" max_results=50
tasks_search_comments query="figma" task_ids=[9049,9050,9051]

tasks_search_text обходит задачи страницами по 50 и локально ищет без учёта регистра в TITLE и DESCRIPTION. Ответ компактный: ID, заголовок, ссылка, проект и фрагменты, без полного описания. Ограничивайте поиск group_id или периодом; max_pages (по умолчанию 60) и max_results (20) не дают молча превратить вызов в неограниченный обход. При stopped_by="max_pages" можно продолжить с next_start; при max_results увеличьте лимит и повторите запрос, так как совпадение могло быть в середине страницы. Для комментариев используйте tasks_search_comments только с уже суженным списком task_ids: каждый кандидат требует отдельного REST-вызова.

Стадии канбана проекта

project_stages group_id=9

Возвращает стадии в порядке по SORT. Для «My Planner» передать group_id=0.

Задачи конкретной канбан-стадии

tasks_by_stage group_id=9 stage_id=65
tasks_by_stage group_id=9 stage_id=65 filter={"RESPONSIBLE_ID": 45}

Пользовательский filter мёржится с GROUP_ID / STAGE_ID так, что их нельзя перебить.

Бриф проекта до стадии «В процессе»

project_brief group_id=9
project_brief group_id=9 include_description=true max_tasks_per_stage=10
project_brief group_id=9 exclude_completed=false
project_brief group_id=9 select=["ID","TITLE","DESCRIPTION","RESPONSIBLE_ID"] max_tasks_per_stage=5

Проходит стадии канбана по порядку и собирает задачи до стадии «В процессе» включительно. По умолчанию завершённые задачи (STATUS=5) исключаются (exclude_completed=true). include_description добавляет DESCRIPTION к дефолтным полям; select задаёт произвольный набор полей. max_tasks_per_stage ограничивает выборку на стадию (в ответе добавляются поля truncated и total_in_stage). Для проектов без канбана автоматически переключается на STATUS-фильтрацию (has_kanban: false). Если в проекте есть задачи с stageId=0, они показываются в отдельной секции unassigned.

Задачи «В процессе»

tasks_in_progress group_id=9
tasks_in_progress group_id=9 in_progress_match=["in progress"]

Шорткат: стадия находится автоматически. Тот же механизм поиска, что в project_brief. Каждая задача содержит вычисляемое поле age_days.

Задачи-долгожители

tasks_stale group_id=9
tasks_stale group_id=9 min_age_days=60 stage_match=["тестирование"]
tasks_stale group_id=9 stage_id=65 min_age_days=14

Находит задачи на стадии, созданные более N дней назад (по createdDate). По умолчанию min_age_days=30, стадия — «В процессе». Каждая задача содержит age_days.

Перегрузка исполнителей

tasks_overload group_id=9
tasks_overload group_id=[9, 21, 31] threshold=3 include_user_names=true

Находит исполнителей с количеством задач «В процессе» больше порога (threshold, по умолчанию 2). Поддерживает несколько проектов. include_user_names=true обогащает результат именами.

Завершённые задачи за период

tasks_completed_period from="2026-04-01" to="2026-04-08" group_id=9
tasks_completed_period from="2026-04-01" responsible_id=45
tasks_completed_period from="2026-04-01" group_id=9 stage_closed_fallback=true

Основной фильтр по CLOSED_DATE. При stage_closed_fallback=true (по умолчанию) дополнительно ищет задачи в финальных стадиях канбана по CHANGED_DATE — ловит задачи, закрытые перемещением по канбану без closedDate. Каждая задача содержит _source: "closed_date" или "stage_fallback". Для проектов без канбана — fallback по STATUS=5 + CHANGED_DATE.

Новые задачи за период

tasks_new_period from="2026-04-01" to="2026-04-08" group_id=9
tasks_new_period from="2026-04-01" include_closed=true

Выборка задач по CREATED_DATE. По умолчанию исключает уже закрытые (STATUS=5). Для раздела «новые направления» в еженедельном отчёте.

Multi-project report

multi_project_report group_ids=[9,21,31] from="2026-07-01" to="2026-07-28"
multi_project_report group_ids=[9,21] from="2026-07-01" max_tasks_per_section=10 include_testing=false

Собирает по каждому проекту активную работу, тестирование и закрытия за период. Закрытия используют ту же fallback-логику, что tasks_completed_period; в проекте без канбана активная работа определяется по STATUS=3. Ответ ограничивает каждую секцию параметром max_tasks_per_section (default 20) и возвращает ошибки конкретного проекта, не отменяя остальные.

Предпросмотр архивирования (read-only)

tasks_archive_dry_run group_id=9
tasks_archive_dry_run group_id=9 final_stage_id=101

Показывает завершённые задачи, которые ещё не лежат в финальной стадии канбана. Ничего не перемещает. Поиск финальной стадии — с конца канбана по подстрокам ["готово","завершено","закрыт","архив"] или по явному final_stage_id.

Архивирование завершённых задач (WRITE)

tasks_archive group_id=9 confirm=true
tasks_archive group_id=9 confirm=true task_ids=[123, 456] final_stage_id=101 limit=5

Требует confirm=true, иначе ничего не делает. Дефолт limit=10, максимум 50. Если task_ids передан (даже пустой массив) — массовая выборка отключена, каждая задача проходит preflight (проверка group_id, STATUS, не уже в финале). Последовательный task.stages.movetask с индивидуальными moved[] / failed[] и from_stage_id для отката.

Загрузка файла в Drive

disk_upload local_path="/tmp/report.pdf"
disk_upload content_base64="JVBERi0xLjcK..." name="report.pdf"
disk_upload local_path="/tmp/report.pdf" folder_id=1739

Если folder_id не указан, сервер пытается загрузить файл в корень персонального Drive текущего пользователя.

Прикрепление файла к задаче

task_attach_file task_id=9049 file_id=6687
task_attach_file task_id=9049 local_path="/tmp/report.pdf"
task_attach_file task_id=9049 content_base64="JVBERi0xLjcK..." name="report.pdf"

Для существующей задачи используется штатный tasks.task.files.attach. Если передан локальный файл или base64-контент, MCP сначала грузит его в Drive, потом прикрепляет к задаче.

Чтение личного диалога

im_chat_messages dialog_id="75"

Если Bitrix24 возвращает файлы в ответе, каждое сообщение дополнительно содержит attachments: [{id,name,size,download_url,detail_url}].

Чтение группового чата

im_chat_messages dialog_id="chat10833"

Если у сообщения есть обсуждение, оно содержит thread: {dialog_id, message_count, is_user_subscribed}. При недоступности im.v2.* верхнеуровневое поле threads_available будет false, но сами сообщения всё равно вернутся.

Треды (комментарии к сообщению канала)

im_thread_messages dialog_id="chat10887" message_id=426029
im_thread_messages dialog_id="chat10887" message_id=412615 limit=50
im_thread_messages dialog_id="chat10887" message_id=426029 thread_dialog_id="chat27219"
im_thread_reply dialog_id="chat10887" message_id=426029 message="Проверю и вернусь с ответом"
im_thread_reply thread_dialog_id="chat27219" message="Уже известный тред"

im_thread_messages по умолчанию скрывает системный маркер «Начало обсуждения»; передайте include_system=true, чтобы его включить. im_thread_reply пишет от имени владельца webhook и умеет отвечать только в уже существующий тред: REST не создаёт первый комментарий под новым сообщением.

Комментарии к публикации канала

im_message_comments dialog_id="chat10907" message_id=414247
im_message_comments dialog_id="chat10907" message_id=414247 include_system=true
im_message_comments dialog_id="chat10907" message_id=414247 comment_dialog_id="chat26615"

Комментарии Bitrix24 хранятся в отдельном скрытом чате type=comment. Публичный REST API не умеет находить его напрямую по message_id, поэтому MCP проверяет ограниченный диапазон свежих chat ID и сверяет parent_chat_id / parent_message_id. Для старых веток увеличьте scan_limit или передайте scan_start_chat_id и scan_end_chat_id. Если comment_dialog_id уже известен, инструмент проверит его принадлежность и прочитает ветку без сканирования. Любой диапазон ограничен 5000 chat ID; за один вызов возвращается до 50 сообщений.

Поиск чата по названию

im_chat_find query="Агент поддержки"
im_chat_find query="support" limit=5

Возвращает доступные текущему пользователю чаты и нормализованный dialog_id (chat<ID> для обычного чата, sg<ID> для чата рабочей группы).

Чат рабочей группы/проекта

workgroup_chat_get group_id=9
workgroup_chat_get group_name="Разработка"

Композиция sonet_group.get + im.chat.get для основного чата проекта/группы. Для проектных чатов dialog_id возвращается в формате sg<group_id>.

Сообщения чата за период

im_chat_messages_period dialog_id="chat16405" date_from="2026-04-24T00:00:00+03:00" date_to="2026-04-24T23:59:59+03:00"
im_chat_messages_period dialog_id="sg9" date_from="2026-04-01" date_to="2026-04-24" limit=200 max_pages=40

Листает im.dialog.messages.get через FIRST_ID от начала истории, фильтрует сообщения по date на стороне MCP и возвращает stopped_by / next_first_id для диагностики длинных чатов. Если в ответе Bitrix есть файлы, сообщения обогащаются полем attachments.

Отправка файла в чат

im_send_file dialog_id="75" local_path="/tmp/report.pdf"
im_send_file dialog_id="chat10833" local_path="/tmp/report.pdf" message="Отправляю отчёт"
im_send_file dialog_id="sg9" file_id=6687 message="Готовый файл из Drive"

Если передан локальный файл или content_base64, используется im.v2.File.upload. Если уже есть file_id в Drive — im.disk.file.commit.

База знаний

kb_list
kb_list type="KNOWLEDGE"
kb_sections site_id=5
kb_sections site_id=5 include_system=true
kb_page_content landing_id=15
kb_page_content landing_id=15 format="text"
kb_search query="VPN" site_id=5
kb_search query="Shadowsocks" site_id=5 max_pages=20

Эти инструменты работают со старыми базами на модуле Landing. kb_list возвращает все доступные базы (standalone KNOWLEDGE и базы рабочих групп GROUP); видны только расшаренные пользователю webhook. kb_sections отдаёт страницы базы по её site_id (scope определяется автоматически, системные страницы скрыты по умолчанию). kb_page_content собирает блоки страницы и склеивает их в markdown (по умолчанию), text или html. kb_search перебирает страницы и их блоки локально, потому что серверный SEARCH_CONTENT ненадёжен: ограничивайте его site_id, max_pages (default 10) и max_results (20). Требуется право webhook landing.

База знаний 2.0

kb2_list
kb2_tree collection_id=123
kb2_document id=77
kb2_search query="Планы на спринт" limit=200
kb2_document_create collection_id=11 parent_id=77 title="20.07-02.08" markdown="..." confirm=false
kb2_document_create collection_id=11 parent_id=77 title="20.07-02.08" markdown="..." expected_preview_key="<preview_key>" confirm=true
kb2_document_delete id=123 confirm=false
kb2_document_delete id=123 expected_title="Документ" expected_updated_at="2026-07-16T10:51:36Z" confirm=true
kb2_document_delete id=123 expected_title="Документ" expected_updated_at="2026-07-16T10:51:36Z" expected_children_key="<children_key>" allow_delete_with_children=true confirm=true
kb2_document_update id=531 markdown="# Новый текст" confirm=false
kb2_document_update id=531 markdown="# Новый текст" expected_updated_at="2026-07-14T15:16:48Z" confirm=true

Документы с адресами /note/document/... обрабатываются отдельными методами note.* через REST 3.0. kb2_tree сохраняет вложенные children и возвращает truncated; kb2_document возвращает исходный Markdown. Поиск выдаёт только первую страницу: при hasMore=true нужно уточнить запрос или увеличить limit. Для чтения требуются scope webhook note и право «Просмотр» у пользователя webhook на нужную базу или документ.

Если у пользователя webhook есть только право «Просмотр», read-only инструменты (kb2_list, kb2_tree, kb2_document, kb2_search) продолжают работать в пределах доступных баз и документов. Write-инструменты могут сформировать preview, но подтверждённые вызовы confirm=true не обходят права Bitrix24: создание, обновление или перемещение в корзину завершится ошибкой доступа, если у пользователя нет соответствующего права на выбранную базу, родителя или документ.

kb2_document_create создаёт новый документ через note.document.add только после preview. Первый вызов выполняется с confirm=false: инструмент проверяет родительский документ, ищет дубли заголовка среди соседних документов, возвращает поля будущего создания и preview_key, но ничего не пишет. confirm=true допустим только после явного подтверждения пользователя в текущем диалоге и с тем же expected_preview_key; если поля создания изменились после preview, операция отменяется. Если в выбранном parent_id уже есть документ с таким же title, создание блокируется, пока пользователь явно не разрешит allow_duplicate_title=true. Bitrix24 дополнительно проверяет право пользователя webhook на создание документа в указанной базе или родителе.

kb2_document_delete перемещает документ в корзину Bitrix24 через note.document.delete только после preview. Первый вызов с confirm=false читает документ, возвращает expected_title, expected_updated_at, метаданные, первые 1000 символов Markdown, список вложенных дочерних документов и children_key. Подтверждённый вызов обязан передать значения из preview; MCP повторно читает документ и отменяет удаление, если title, updatedAt или список дочерних документов изменились. Если у документа есть дочерние документы, удаление по умолчанию блокируется; пользователь должен явно разрешить это через allow_delete_with_children=true и передать тот же expected_children_key. После успешного удаления документ исчезает из дерева и поиска, но может оставаться доступен прямым note.document.get по ID как объект в корзине. Bitrix24 дополнительно проверяет право пользователя webhook на удаление.

Если пользователь просит удалить документ по названию, агент сначала должен выполнить поиск и проверить неоднозначность. При нескольких совпадениях удалять нельзя: нужно показать пользователю варианты с documentId, collectionId, parentId, родителем/путём из kb2_tree и кратким preview/snippet, затем попросить уточнить, какой именно документ удалить. Только после выбора конкретного documentId можно вызывать kb2_document_delete confirm=false и затем запрашивать финальное подтверждение на confirm=true.

kb2_document_update заменяет переданный заголовок и/или всё содержимое Markdown. Первый вызов всегда выполняется с confirm=false: инструмент читает актуальный документ, возвращает preview с expected_updated_at и ничего не меняет. После показа изменений пользователь должен явно подтвердить именно эту запись в текущем диалоге. Только после такого ответа агент может повторить вызов с confirm=true и тем же expected_updated_at; самостоятельно подтверждать операцию или считать исходный запрос подтверждением запрещено. Перед записью MCP повторно читает документ. Если updatedAt изменился после preview, операция отменяется с DOCUMENT_CHANGED_SINCE_PREVIEW, и требуется новый preview и новое подтверждение. Запрос всегда отправляется с overwrite=false. Принудительная перезапись через MCP не поддерживается. Bitrix24 выполняет запись только при наличии у пользователя webhook права «Редактирование».

Bitrix24 поддерживает совместное редактирование и может принять REST-обновление при открытом веб-редакторе, уведомив редактора о новой версии. Публичный REST API не предоставляет отдельного метода проверки активных редакторов. Проверка updatedAt защищает от отправки изменений поверх уже сохранённой новой версии, но не определяет наличие несохранённого текста в открытом редакторе.

При NOTE_DOCUMENT_HAS_UNSAVED_CHANGES ответ содержит pending_update с ID и полным набором предложенных полей. Эти данные остаются в контексте текущего чата, поэтому пользователь может позже написать «попробовать ещё раз» — это считается явным подтверждением повторить именно ожидающее изменение. MCP не хранит черновик на диске или в Bitrix24: в новом чате preview нужно сформировать заново.

Универсальный вызов API

bitrix_call method="crm.lead.list" params={"filter": {"STATUS_ID": "NEW"}}

Multi-project report (cookbook)

Пошаговое руководство по сборке сводки по нескольким проектам через композицию инструментов — см. artifacts/cookbook-multi-project-report.md.

Детали задачи для summary / отчёта

tasks_get id=9049 select=["ID","TITLE","DESCRIPTION","STATUS","DEADLINE","CREATED_DATE","CLOSED_DATE","RESPONSIBLE_ID","CREATED_BY","GROUP_ID","STAGE_ID"]
tasks_get id=9049 include_attachments=true

Сервер не обрезает DESCRIPTION — возвращает поле в том виде, в котором его отдаёт Bitrix24. При include_attachments=true дополнительно возвращаются нормализованные вложения задачи из UF_TASK_WEBDAV_FILES.