Bitrix24 MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 через |
Полный список выводит 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 не копируются.
Установка (администратор)
Сервисный пользователь. Заведите в Битрикс24 пользователя «ИИ-агент» с нужными правами CRM и задач.
Входящий вебхук. От его имени создайте вебхук (Разработчикам → Другое → Входящий вебхук) с правами
crm, task, user, imbot, im, department, sonet_group, calendar, bizproc, lists.Сервер. Нужна машина в контуре, которой доступны портал и 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.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}}.Проверка, регистрация бота, запуск:
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— удалить бота.
Что включается настройками
Функция | Настройка | Что даёт |
Ответы на упоминания в таймлайне |
| агент отвечает на @упоминание в комментариях объектов этих типов |
Отслеживание объектов |
| по команде «следи за таймлайном сделки 123» отвечает на все новые комментарии |
Автопомощь |
| по новому входящему письму или файлу сам готовит справку в таймлайн и/или в личку ответственному |
Участник бизнес-процессов |
| выполняет назначенные ему шаги процессов, сложное передаёт человеку |
Только чтение |
| агент отвечает, но ничего не меняет |
Круг пользователей |
| кому можно общаться с агентом |
Отключение инструментов |
| убрать отдельные действия |
Регламенты |
| тон, правила, состав справок — текстом, без программирования |
Все параметры с комментариями — в .env.example.
Как пользуются сотрудники
Личный чат с ботом. Пишут обычным языком:
«Мои задачи на неделю»;
«Найди контакт Иванов, что по его сделкам?»;
«Переведи сделку 123 на стадию „Договор“ и поставь Петрову задачу подготовить счёт к пятнице»;
«Что мне на согласование?»;
«Когда свободны Сидоров и Козлова в четверг?».
Переписка и документы:
«Какая переписка с клиентом по проекту 15?»;
«Что он пишет в последнем письме? Подготовь ответ»;
«Прочитай договор во вложении и выпиши сроки, суммы и штрафы».
Чат по объекту. «Создай чат по проекту 15» или «привяжи этот чат к сделке 123»; можно также добавить бота в штатный чат карточки. После этого вопросы («какая стадия?», «что просрочено?») относятся к этому объекту. В групповом чате бота упоминают через @.
Таймлайн. Комментарий @ИИ-агент что по этой сделке? — агент отвечает комментарием.
Автопомощь. Пришло письмо от клиента — в таймлайне появляется справка «ИИ-помощник»: суть, что просят, риски, следующие шаги, черновик ответа.
Команды в чате: /help, /clear (забыть историю диалога), /context (к чему привязан чат), /whoami (с чьими правами работает агент), /memory и /forget (личная память ассистента).
Как пользуются авторы бизнес-процессов
В дизайнере добавляют «Утверждение», «Ознакомление» или «Запрос доп. информации» и назначают ответственным «ИИ-агент».
В описании задания пишут инструкцию: «Проверь договор во вложениях. Утверди, если оплата не позже 30 дней, иначе отклони и перечисли нарушения».
Агент изучает документ, письма и файлы и выполняет шаг: утверждает или отклоняет, отмечает ознакомление, заполняет поля. Значения полей доступны следующим шагам процесса.
Если данных мало, решение рискованное или не входит в разрешённые (
BP_AGENT_DECISIONS), задание передаётся человеку изBP_AGENT_ESCALATE_TOс причиной и мнением агента и делегируется ему.
Подробно и с примерами — в docs/BP_PARTICIPANT.md.
Собрать новый шаблон процесса агент не может: Битрикс разрешает загрузку шаблонов только приложениям, а роботов на стадиях через REST не настроить.
Права: универсальный агент и личные ассистенты
У агента два режима работы с правами:
Универсальный агент | Личный ассистент | |
Права | свои: сервисная учётка «ИИ-агент», вебхук | права сотрудника: работает через вебхук, который создал сам сотрудник |
От чьего имени действует | от «ИИ-агента» | от сотрудника: комментарии, задачи, изменения, согласования |
Что видит | всё, что разрешено сервисной учётке | ровно то, что видит сотрудник в Битрикс24 |
Память | история диалогов | история диалогов и личная память: стиль общения, роль, клиенты, коллеги, привычки |
Где работает | бизнес-процессы, автопомощь, групповые чаты и чаты объектов, таймлайн, MCP | личный чат с ботом «ИИ-агент» или отдельный скрытый бот («Ассистент Анны»), который отвечает только владельцу; MCP |
Важно про универсального агента. Он не проверяет права собеседника: в Битрикс24 нет REST-метода «видит ли пользователь X эту сделку». Поэтому давайте сервисной учётке только те воронки, смарт-процессы и разделы, которые можно показывать всем пользователям агента и которые нужны для бизнес-процессов и автопомощи.
Как настроить личного ассистента
Сотрудник сам создаёт входящий вебхук в своей учётке и передаёт URL администратору защищённым способом, не в чате и не по почте. Агент проверяет владельца и чужой вебхук не принимает.
Администратор добавляет сотрудника в
personal_agents.toml(пример —personal_agents.example.toml). Там задаются:имя ассистента;
отдельный бот или общий чат (
own_bot);можно ли изменять данные (
allow_write);вести ли память (
memory);персональные инструкции (
prompt, например «обращайся на „ты“, отвечай кратко»).
b24agent personalпроверяет, что вебхук работает и принадлежит именно этому сотруднику.b24agent setupрегистрирует личных ботов, и бот сам пишет сотруднику приветствие.
Личная память
Ассистент сам запоминает устойчивые предпочтения. Можно попросить явно: «запомни, что отчёт я сдаю по пятницам».
Память подставляется в каждый разговор с владельцем. У универсального агента её нет.
Команды:
/memory— что запомнено; «забудь [номер]» — удалить заметку;/forget— очистить всё;/whoami— с чьими правами сейчас идёт работа.Память хранится локально у агента (
data/agent.sqlite3) и в Битрикс24 не пишется. Пароли и токены не сохраняются.
Режим личного чата: PRIVATE_CHAT_MODE
Значение | Поведение |
| если у сотрудника есть личный ассистент — отвечает он, иначе универсальный агент |
| без личного ассистента отказ. Самый безопасный режим: через личный чат никто не получит данные сверх своих прав |
| всегда универсальный агент |
Исходящие вебхуки и размещение агента внутри Битрикс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 → Настройки → Права доступа; права в задачах, группах, на Диске | |
Вебхук универсального агента | под учёткой «ИИ-агент»: Разработчикам → Другое → Входящий вебхук; права | |
Разрешить сотрудникам создавать вебхуки (для личных ассистентов) | Настройки → Безопасность → Интеграции Битрикс24 → «Кому разрешить создавать входящие вебхуки» | |
Вебхук личного ассистента | создаёт сам сотрудник в своей учётке (те же права, без | |
Шаги бизнес-процессов для агента | дизайнер БП: «Утверждение», «Ознакомление», «Запрос доп. информации», ответственный — «ИИ-агент», инструкция в описании задания | |
Увольнение сотрудника с личным ассистентом | удалить вебхук сотрудника. Если выбрать «Сохранить интеграции и уволить», вебхук продолжит работать |
На сервере агента (файлы)
Файл | Что в нём | Пример / описание |
| подключение к порталу и LiteLLM, бот, таймлайн, автопомощь, БП, права и ограничения, политика |
|
| личные ассистенты: сотрудник, вебхук (через переменную окружения), свой бот, запись, память, инструкции | |
файлы регламентов ( | тон, правила компании, состав справок, правила решений в БП — обычным текстом | |
| собственные инструменты компании | |
| история диалогов, личная память, привязки чатов, курсоры опроса, кэш файлов. Бэкапьте, это рабочие данные агента |
Секреты (вебхуки, LLM_API_KEY) храните только в .env или в переменных окружения службы. .env и personal_agents.toml в репозиторий не попадают (.gitignore).
Частые задачи администратора
Задача | Что сделать |
Проверить, что всё подключено |
|
Запустить или обновить бота |
|
Добавить личного ассистента | вебхук от сотрудника → запись в |
Проверить личного ассистента без чата |
|
Закрыть доступ к данным сверх прав сотрудника |
|
Ограничить круг пользователей |
|
Включить режим только чтения |
|
Отключить отдельное действие |
|
Включить ответы в таймлайне |
|
Включить автопомощь по письмам и файлам |
|
Включить участие в бизнес-процессах |
|
Разрешить агенту редкий метод REST |
|
Посмотреть, какие инструменты активны |
|
Подключить ИИ-клиент через MCP |
|
Посмотреть состояние сервиса | логи службы ( |
Удалить бота |
|
Порядок чтения документации
Этот README — обзор, установка, карта настроек.
docs/RIGHTS_AND_AGENTS.md — права, личные ассистенты, безопасность. Прочитайте до пилота.
.env.example— все параметры.По задаче: 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.
Документ | О чём |
что умеет агент, каналы, компоненты кода, безопасность | |
как дорабатывать: плагины, контракт инструмента, тесты, точки расширения | |
для администраторов: права агента и сотрудников, личные ассистенты и их память, увольнение, варианты размещения | |
MCP Server: подключение клиентов, все 42 инструмента с параметрами, примеры, безопасность | |
агент в бизнес-процессах: настройка в дизайнере, примеры | |
справочник 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 ещё не проверен.
Что проверить на пилоте в первую очередь:
Есть ли на коробке imbot.v2 — покажет
b24agent check. Без него остаётсяBOT_API=v1, и тогда портал должен уметь достучаться до агента.Как модель вызывает инструменты —
checkи несколько вопросов черезask.Работает ли выборка объектов по активности (
lastActivityTime): на ней держатся таймлайн и автопомощь.В каком виде портал отдаёт вложения писем — на реальном письме с файлом.
Выполнение и делегирование заданий БП сервисного пользователя — на тестовом процессе.
Разрешено ли рядовым сотрудникам создавать входящие вебхуки (настройки безопасности портала).
Может ли бот первым написать сотруднику в личку: на этом построено приветствие личного бота.
Скрывается ли личный бот из поиска на вашей версии коробки (
isHidden).
История версий
Версия | Что вошло |
2.0 | основа под коробку: CRM, смарт-процессы, задачи, чат-бот, таймлайн, LLM, MCP |
2.1 | закрытый контур (imbot.v2 fetch, опрос таймлайна), плагины, новые инструменты, справочник API коробки |
2.2 | письма и файлы объектов, чтение документов, автопомощь |
2.3 | агент как участник бизнес-процессов |
2.4 | личные ассистенты с правами сотрудника и личной памятью; режимы личного чата; MCP |
Лицензия: MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server enabling AI agents to manage Bitrix24 features via standardized protocol
AI agent platform: manage leads, conversations, bots, calendar and CRM via MCP.
CRM + visual automation builder AI agents can drive via MCP: contacts, tags, maps, email/SMS flows.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to interact with Bitrix24 CRM through comprehensive tools for managing contacts, deals, leads, companies, tasks, and users, with advanced filtering, search capabilities, and sales team performance monitoring.5035MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with Bitrix24 CRM for managing contacts, deals, tasks, and leads via a comprehensive set of tools. It supports advanced features like sales team monitoring, performance analytics, and automated CRM searching.-
- FlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for Bitrix24 CRM integration that enables AI agents to manage contacts, deals, tasks, leads, and companies. It also provides advanced tools for sales team monitoring, performance analytics, and automated CRM search capabilities.7 npm-
- AlicenseNot gradedqualityDmaintenanceMCP server for Bitrix24 CRM integration, enabling AI agents to manage contacts, deals, tasks, and more via natural language.MIT