Skip to main content
Glama
Bitrix24 MCP Server

Bitrix24 MCP Server

by rusnetru

b24agent — ИИ-сотрудник и MCP Server для коробочного Битрикс24

b24agent — сервис, который ставится внутри корпоративной сети рядом с коробочным Битрикс24 и подключается к внутренней LLM (например, Qwen) через LiteLLM. Он понимает данные портала, общается с сотрудниками в чатах и таймлайне, читает переписку и документы и участвует в бизнес-процессах.

Входящий доступ не нужен: все соединения идут от агента к порталу и к LLM.

Агент работает в трёх ролях:

Роль

Кто пользуется

Как

Чат-бот «ИИ-агент»

сотрудники

личный чат, групповые чаты, чаты по объектам, комментарии в таймлайне

Личный ассистент сотрудника

конкретный сотрудник

работает с правами сотрудника через его вебхук и помнит его особенности работы и общения

Фоновый помощник

ответственные, авторы процессов

сам готовит справки по новым письмам и файлам, выполняет назначенные ему шаги бизнес-процессов

MCP-сервер

ИИ-клиенты (Claude Desktop, Cursor, внутренние платформы)

42 инструмента по протоколу MCP — docs/MCP_SERVER.md

Сотрудник ─ чат / @упоминание / задание БП ─► Битрикс24 (коробка)
                                              ▲  REST через входящий вебхук
                                              │  (все запросы исходящие от агента)
                                    b24agent serve ◄──► LiteLLM ◄──► Qwen
                                    b24agent mcp   ◄──► MCP-клиенты

Что агент видит и умеет

Область

Возможности

CRM

сделки, лиды, контакты, компании, предложения, счета: поиск, карточки с понятными названиями полей, создание, изменение, смена стадий, связи, история стадий, дела

Смарт-процессы

любые, по названию или ID: поля, воронки, стадии, элементы

Переписка

письма из таймлайна: список, полный текст, адресаты, вложения

Документы

все файлы объекта на Диске (поля, вложения комментариев, писем и дел). Читаются PDF, Word, Excel, PowerPoint, ODT, RTF, TXT, CSV, HTML, EML

Задачи

мои задачи, задачи по объекту, создание с привязкой к CRM, изменение, статусы, комментарии

Люди и структура

поиск сотрудников, подразделения, рабочие группы и проекты

Календарь

события, занятость коллег, создание встреч

Бизнес-процессы

мои согласования, согласовать или отклонить, запуск процесса; агент сам может быть участником шага

Универсальные списки

чтение и добавление элементов

Всё остальное

любой метод REST через bitrix_call (по умолчанию только чтение)

Полный список выводит b24agent tools.

Related MCP server: Bitrix24 MCP Server

Как это работает

  • Права = права пользователя вебхука. Универсальный агент работает через вебхук сервисной учётки «ИИ-агент» и действует от её имени. Личный ассистент работает через вебхук конкретного сотрудника, с его правами и от его имени (см. раздел «Права» ниже).

  • Сообщения боту агент сам забирает с портала раз в несколько секунд (imbot.v2, режим fetch).

  • Таймлайн, письма, файлы и задания БП агент получает опросом: раз в 1–2 минуты находит объекты с новой активностью и свои задания. Подписаться на события через вебхук Битрикс не даёт (event.bind → WRONG_AUTH_TYPE).

  • LLM. Модель сама выбирает инструменты, до 10 шагов на вопрос. Учтены особенности Qwen: блоки <think> вырезаются, вызовы <tool_call> в тексте распознаются. Если прокси не поддерживает tools, есть запасной JSON-режим.

  • Хранение. Локально лежат только история диалогов, привязки чатов, отслеживаемые объекты и кэш прочитанных файлов (SQLite в data/). Данные CRM не копируются.


Установка (администратор)

  1. Сервисный пользователь. Заведите в Битрикс24 пользователя «ИИ-агент» с нужными правами CRM и задач.

  2. Входящий вебхук. От его имени создайте вебхук (Разработчикам → Другое → Входящий вебхук) с правами crm, task, user, imbot, im, department, sonet_group, calendar, bizproc, lists.

  3. Сервер. Нужна машина в контуре, которой доступны портал и LiteLLM, с Python 3.11+ или uv:

git clone https://github.com/rusnetru/bitrix24-ai-agent-MCP_Server.git && cd bitrix24-ai-agent-MCP_Server
uv sync            # или: pip install -e .
cp .env.example .env
  1. .env. Минимум:

    • BITRIX_WEBHOOK_URL;

    • BITRIX_VERIFY_SSL — путь к CA, если у портала самоподписанный сертификат;

    • LLM_BASE_URL, LLM_API_KEY, LLM_MODEL — LiteLLM и имя модели в нём.

    Для Qwen3 можно отключить «размышления»: LLM_EXTRA_BODY={"chat_template_kwargs":{"enable_thinking":false}}.

  2. Проверка, регистрация бота, запуск:

uv run b24agent check     # портал, права, imbot.v2, REST 3.0, LLM и поддержка tools
uv run b24agent setup     # регистрирует бота «ИИ-агент» (imbot.v2, eventMode=fetch)
uv run b24agent serve     # работа агента

Для постоянной работы запустите b24agent serve как службу (systemd, NSSM, Docker).

Другие команды:

  • b24agent ask "вопрос" — спросить агента из консоли;

  • b24agent tools — список инструментов;

  • b24agent mcp — MCP-сервер;

  • b24agent personal — проверить личных ассистентов;

  • b24agent ask --as 15 "…" и b24agent mcp --as 15 — работать как личный ассистент сотрудника 15;

  • b24agent unregister — удалить бота.

Что включается настройками

Функция

Настройка

Что даёт

Ответы на упоминания в таймлайне

TIMELINE_SCAN_TYPES=deal,1038

агент отвечает на @упоминание в комментариях объектов этих типов

Отслеживание объектов

TIMELINE_POLL_INTERVAL=30

по команде «следи за таймлайном сделки 123» отвечает на все новые комментарии

Автопомощь

AUTO_ASSIST_TYPES=1038,deal, AUTO_ASSIST_TARGET=timeline,chat

по новому входящему письму или файлу сам готовит справку в таймлайн и/или в личку ответственному

Участник бизнес-процессов

BP_AGENT=true, BP_AGENT_ESCALATE_TO=<ID>

выполняет назначенные ему шаги процессов, сложное передаёт человеку

Только чтение

AGENT_ALLOW_WRITE=false

агент отвечает, но ничего не меняет

Круг пользователей

AGENT_ALLOWED_USERS=1,15,27

кому можно общаться с агентом

Отключение инструментов

TOOLS_DISABLED=bp_start,crm_add

убрать отдельные действия

Регламенты

AGENT_PROMPT_FILE, AUTO_ASSIST_PROMPT_FILE, BP_AGENT_PROMPT_FILE

тон, правила, состав справок — текстом, без программирования

Все параметры с комментариями — в .env.example.


Как пользуются сотрудники

Личный чат с ботом. Пишут обычным языком:

  • «Мои задачи на неделю»;

  • «Найди контакт Иванов, что по его сделкам?»;

  • «Переведи сделку 123 на стадию „Договор“ и поставь Петрову задачу подготовить счёт к пятнице»;

  • «Что мне на согласование?»;

  • «Когда свободны Сидоров и Козлова в четверг?».

Переписка и документы:

  • «Какая переписка с клиентом по проекту 15?»;

  • «Что он пишет в последнем письме? Подготовь ответ»;

  • «Прочитай договор во вложении и выпиши сроки, суммы и штрафы».

Чат по объекту. «Создай чат по проекту 15» или «привяжи этот чат к сделке 123»; можно также добавить бота в штатный чат карточки. После этого вопросы («какая стадия?», «что просрочено?») относятся к этому объекту. В групповом чате бота упоминают через @.

Таймлайн. Комментарий @ИИ-агент что по этой сделке? — агент отвечает комментарием.

Автопомощь. Пришло письмо от клиента — в таймлайне появляется справка «ИИ-помощник»: суть, что просят, риски, следующие шаги, черновик ответа.

Команды в чате: /help, /clear (забыть историю диалога), /context (к чему привязан чат), /whoami (с чьими правами работает агент), /memory и /forget (личная память ассистента).

Как пользуются авторы бизнес-процессов

  1. В дизайнере добавляют «Утверждение», «Ознакомление» или «Запрос доп. информации» и назначают ответственным «ИИ-агент».

  2. В описании задания пишут инструкцию: «Проверь договор во вложениях. Утверди, если оплата не позже 30 дней, иначе отклони и перечисли нарушения».

  3. Агент изучает документ, письма и файлы и выполняет шаг: утверждает или отклоняет, отмечает ознакомление, заполняет поля. Значения полей доступны следующим шагам процесса.

  4. Если данных мало, решение рискованное или не входит в разрешённые (BP_AGENT_DECISIONS), задание передаётся человеку из BP_AGENT_ESCALATE_TO с причиной и мнением агента и делегируется ему.

Подробно и с примерами — в docs/BP_PARTICIPANT.md.

Собрать новый шаблон процесса агент не может: Битрикс разрешает загрузку шаблонов только приложениям, а роботов на стадиях через REST не настроить.


Права: универсальный агент и личные ассистенты

У агента два режима работы с правами:

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

Личный ассистент

Права

свои: сервисная учётка «ИИ-агент», вебхук BITRIX_WEBHOOK_URL

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

От чьего имени действует

от «ИИ-агента»

от сотрудника: комментарии, задачи, изменения, согласования

Что видит

всё, что разрешено сервисной учётке

ровно то, что видит сотрудник в Битрикс24

Память

история диалогов

история диалогов и личная память: стиль общения, роль, клиенты, коллеги, привычки

Где работает

бизнес-процессы, автопомощь, групповые чаты и чаты объектов, таймлайн, MCP

личный чат с ботом «ИИ-агент» или отдельный скрытый бот («Ассистент Анны»), который отвечает только владельцу; MCP --as

Важно про универсального агента. Он не проверяет права собеседника: в Битрикс24 нет REST-метода «видит ли пользователь X эту сделку». Поэтому давайте сервисной учётке только те воронки, смарт-процессы и разделы, которые можно показывать всем пользователям агента и которые нужны для бизнес-процессов и автопомощи.

Как настроить личного ассистента

  1. Сотрудник сам создаёт входящий вебхук в своей учётке и передаёт URL администратору защищённым способом, не в чате и не по почте. Агент проверяет владельца и чужой вебхук не принимает.

  2. Администратор добавляет сотрудника в personal_agents.toml (пример — personal_agents.example.toml). Там задаются:

    • имя ассистента;

    • отдельный бот или общий чат (own_bot);

    • можно ли изменять данные (allow_write);

    • вести ли память (memory);

    • персональные инструкции (prompt, например «обращайся на „ты“, отвечай кратко»).

  3. b24agent personal проверяет, что вебхук работает и принадлежит именно этому сотруднику.

  4. b24agent setup регистрирует личных ботов, и бот сам пишет сотруднику приветствие.

Личная память

  • Ассистент сам запоминает устойчивые предпочтения. Можно попросить явно: «запомни, что отчёт я сдаю по пятницам».

  • Память подставляется в каждый разговор с владельцем. У универсального агента её нет.

  • Команды: /memory — что запомнено; «забудь [номер]» — удалить заметку; /forget — очистить всё; /whoami — с чьими правами сейчас идёт работа.

  • Память хранится локально у агента (data/agent.sqlite3) и в Битрикс24 не пишется. Пароли и токены не сохраняются.

Режим личного чата: PRIVATE_CHAT_MODE

Значение

Поведение

personal (по умолчанию)

если у сотрудника есть личный ассистент — отвечает он, иначе универсальный агент

personal_only

без личного ассистента отказ. Самый безопасный режим: через личный чат никто не получит данные сверх своих прав

service

всегда универсальный агент

Исходящие вебхуки и размещение агента внутри Битрикс24

  • Исходящие вебхуки проблему прав не решают. Они только сообщают о событии и не дают действовать от имени пользователя. Кроме того, в коробке они идут через облачную очередь Битрикс24, что не подходит для закрытого контура.

  • Встроить агента в Битрикс24 можно двумя способами:

    • Локальное приложение даёт права каждого сотрудника без раздачи вебхуков и встройки в интерфейс, например вкладку в карточке. Но в коробке токены выдаются через внешний oauth.bitrix24.tech, а это для закрытого контура обычно неприемлемо.

    • Свой PHP-модуль на портале с REST-методами «выполнить от имени сотрудника с проверкой его прав». Тогда хватит одного сервисного вебхука, а права проверяет сам Битрикс24. Нужна PHP-разработка и сопровождение при обновлениях коробки.

  • LLM в любом случае остаётся отдельным сервисом: внутрь Битрикс24 переносится только проверка прав и выполнение действий. Для пилота и десятков ассистентов подходит текущая схема с вебхуками сотрудников. При масштабировании на сотни человек стоит перейти на PHP-модуль.

Подробно, с рисками, увольнением сотрудников и всеми настройками, — в docs/RIGHTS_AND_AGENTS.md.

Безопасность

  • Агент видит и меняет только то, что разрешено пользователю вебхука: сервисной учётке для универсального агента, сотруднику для личного ассистента.

  • Автопомощь и участие в бизнес-процессах работают только на чтение. Решение по заданию выполняет код после проверки ответа модели, а не сама модель.

  • bitrix_call по умолчанию разрешает только читающие методы. Опасные методы (удаление, события, пользователи, боты и др.) закрыты даже при BITRIX_CALL=full, вызов через batch запрещён.

  • Данные уходят только во внутреннюю LLM через LiteLLM. Секреты лежат в .env, он не коммитится.

Администраторам: где что настраивать

Карта настроек агента: что, где и в каком документе описано.

В Битрикс24 (интерфейс портала)

Задача

Где

Подробности

Сервисная учётка универсального агента и её права

Пользователи → новый пользователь «ИИ-агент»; права в CRM → Настройки → Права доступа; права в задачах, группах, на Диске

RIGHTS_AND_AGENTS.md

Вебхук универсального агента

под учёткой «ИИ-агент»: Разработчикам → Другое → Входящий вебхук; права crm, task, user, imbot, im, department, sonet_group, calendar, bizproc, lists

Установка

Разрешить сотрудникам создавать вебхуки (для личных ассистентов)

Настройки → Безопасность → Интеграции Битрикс24 → «Кому разрешить создавать входящие вебхуки»

RIGHTS_AND_AGENTS.md

Вебхук личного ассистента

создаёт сам сотрудник в своей учётке (те же права, без imbot, плюс disk)

RIGHTS_AND_AGENTS.md

Шаги бизнес-процессов для агента

дизайнер БП: «Утверждение», «Ознакомление», «Запрос доп. информации», ответственный — «ИИ-агент», инструкция в описании задания

BP_PARTICIPANT.md

Увольнение сотрудника с личным ассистентом

удалить вебхук сотрудника. Если выбрать «Сохранить интеграции и уволить», вебхук продолжит работать

RIGHTS_AND_AGENTS.md

На сервере агента (файлы)

Файл

Что в нём

Пример / описание

.env

подключение к порталу и LiteLLM, бот, таймлайн, автопомощь, БП, права и ограничения, политика bitrix_call

.env.example с комментариями к каждому параметру

personal_agents.toml

личные ассистенты: сотрудник, вебхук (через переменную окружения), свой бот, запись, память, инструкции

personal_agents.example.toml, RIGHTS_AND_AGENTS.md

файлы регламентов (AGENT_PROMPT_FILE, AUTO_ASSIST_PROMPT_FILE, BP_AGENT_PROMPT_FILE, prompt_file у ассистента)

тон, правила компании, состав справок, правила решений в БП — обычным текстом

ARCHITECTURE.md, BP_PARTICIPANT.md

plugins/*.py

собственные инструменты компании

EXTENDING.md, plugins/_example_sales.py

data/agent.sqlite3

история диалогов, личная память, привязки чатов, курсоры опроса, кэш файлов. Бэкапьте, это рабочие данные агента

ARCHITECTURE.md

Секреты (вебхуки, LLM_API_KEY) храните только в .env или в переменных окружения службы. .env и personal_agents.toml в репозиторий не попадают (.gitignore).

Частые задачи администратора

Задача

Что сделать

Проверить, что всё подключено

b24agent check: портал, права вебхука, imbot.v2, REST 3.0, LLM и вызов инструментов

Запустить или обновить бота

b24agent setup, затем перезапустить службу b24agent serve

Добавить личного ассистента

вебхук от сотрудника → запись в personal_agents.toml → b24agent personal → b24agent setup → перезапуск

Проверить личного ассистента без чата

b24agent ask --as 15 "какие у меня задачи?"

Закрыть доступ к данным сверх прав сотрудника

PRIVATE_CHAT_MODE=personal_only и минимальные права сервисной учётки

Ограничить круг пользователей

AGENT_ALLOWED_USERS=...; владельцы личных ассистентов допускаются всегда

Включить режим только чтения

AGENT_ALLOW_WRITE=false (для всех) или allow_write = false (для ассистента)

Отключить отдельное действие

TOOLS_DISABLED=bp_start,crm_add (для всех) или tools_disabled у ассистента

Включить ответы в таймлайне

TIMELINE_SCAN_TYPES=deal,1038

Включить автопомощь по письмам и файлам

AUTO_ASSIST_TYPES=..., AUTO_ASSIST_TARGET=timeline,chat

Включить участие в бизнес-процессах

BP_AGENT=true, BP_AGENT_ESCALATE_TO=<ID>; для старта BP_AGENT_DECISIONS=ok

Разрешить агенту редкий метод REST

BITRIX_CALL=full + BITRIX_CALL_ALLOW=метод

Посмотреть, какие инструменты активны

b24agent tools

Подключить ИИ-клиент через MCP

b24agent mcp (права агента) или b24agent mcp --as 15 (права сотрудника) — MCP_SERVER.md

Посмотреть состояние сервиса

логи службы (LOG_LEVEL=INFO), http://<агент>:8090/health

Удалить бота

b24agent unregister

Порядок чтения документации

  1. Этот README — обзор, установка, карта настроек.

  2. docs/RIGHTS_AND_AGENTS.md — права, личные ассистенты, безопасность. Прочитайте до пилота.

  3. .env.example — все параметры.

  4. По задаче: BP_PARTICIPANT.md (бизнес-процессы), MCP_SERVER.md (MCP-клиенты), ARCHITECTURE.md (как устроено), EXTENDING.md и BITRIX_BOX_API.md (доработка).

Развитие внутри контура

  • Плагины. Свой инструмент — Python-файл в plugins/ с функцией register(tb). Он сразу доступен боту и MCP-клиентам. Плагином можно также переопределить или убрать встроенный инструмент. Пример: plugins/_example_sales.py.

  • Код. Инструменты лежат по модулям в b24agent/tools/: crm, documents, tasks, users, org, processes, generic, chat.

  • Тесты: uv sync --group dev && uv run pytest. Линтер: uv run ruff check b24agent tests.

Документ

О чём

docs/ARCHITECTURE.md

что умеет агент, каналы, компоненты кода, безопасность

docs/EXTENDING.md

как дорабатывать: плагины, контракт инструмента, тесты, точки расширения

docs/RIGHTS_AND_AGENTS.md

для администраторов: права агента и сотрудников, личные ассистенты и их память, увольнение, варианты размещения

docs/MCP_SERVER.md

MCP Server: подключение клиентов, все 42 инструмента с параметрами, примеры, безопасность

docs/BP_PARTICIPANT.md

агент в бизнес-процессах: настройка в дизайнере, примеры

docs/BITRIX_BOX_API.md

справочник REST API коробки для закрытого контура (по apidocs.bitrix24.ru), бэклог доработок

MCP Server

b24agent mcp — MCP-сервер (stdio). Он подключает к коробочному Битрикс24 любой ИИ-клиент: Claude Desktop, Claude Code, Cursor, VS Code, внутренние агентные платформы. Клиент получает 42 инструмента:

Группа

Инструменты

CRM и смарт-процессы

поиск, карточки, изменение, стадии, история, дела

Переписка и документы на Диске

письма, файлы объекта, чтение текста PDF/Office

Задачи

список, карточка, создание, изменение, комментарии

Сотрудники и оргструктура

поиск сотрудников, подразделения, рабочие группы

Календарь

события, занятость, создание встреч

Бизнес-процессы и списки

задания БП, запуск процессов, универсальные списки

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

любой метод портала с политикой безопасности

LLM на стороне сервера не нужна. Права ограничены пользователем вебхука, режим только чтения и плагины компании действуют так же, как у чат-бота. Подробное описание всех функций — в docs/MCP_SERVER.md.

{
  "mcpServers": {
    "bitrix24": {
      "command": "uv",
      "args": ["--directory", "/path/to/bitrix24-ai-agent-MCP_Server", "run", "b24agent", "mcp"]
    }
  }
}

Состояние

Версия 2.4.0. Проходят 37 автотестов на заглушках портала и LLM и проверка линтером. Запуск на настоящей коробке и с корпоративной Qwen ещё не проверен.

Что проверить на пилоте в первую очередь:

  1. Есть ли на коробке imbot.v2 — покажет b24agent check. Без него остаётся BOT_API=v1, и тогда портал должен уметь достучаться до агента.

  2. Как модель вызывает инструменты — check и несколько вопросов через ask.

  3. Работает ли выборка объектов по активности (lastActivityTime): на ней держатся таймлайн и автопомощь.

  4. В каком виде портал отдаёт вложения писем — на реальном письме с файлом.

  5. Выполнение и делегирование заданий БП сервисного пользователя — на тестовом процессе.

  6. Разрешено ли рядовым сотрудникам создавать входящие вебхуки (настройки безопасности портала).

  7. Может ли бот первым написать сотруднику в личку: на этом построено приветствие личного бота.

  8. Скрывается ли личный бот из поиска на вашей версии коробки (isHidden).

История версий

Версия

Что вошло

2.0

основа под коробку: CRM, смарт-процессы, задачи, чат-бот, таймлайн, LLM, MCP

2.1

закрытый контур (imbot.v2 fetch, опрос таймлайна), плагины, новые инструменты, справочник API коробки

2.2

письма и файлы объектов, чтение документов, автопомощь

2.3

агент как участник бизнес-процессов

2.4

личные ассистенты с правами сотрудника и личной памятью; режимы личного чата; MCP --as

Лицензия: MIT.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers