Привет! Мы — партнеры Битрикс24 и создаем для бизнеса приложения с генеративным ИИ, интегрируя их с корпоративными порталами.
В этой статье мы расскажем о созданном нами решении, которое позволяет любым разработчикам легко подключать свои чаты и другие приложения с LLM-моделями к Битрикс24. Речь идет о MCP-сервере — помощнике для ИИ, который позволяет получать из портала Битрикс24, например из раздела CRM, точные данные для ответа пользователю.
Почему мы вообще решили сделать MCP-сервер именно для Битрикс24?
В «Карточке» мы начали внедрять первые обработки данных генеративным ИИ в Битрикс24 в 2023 году, разворачивая их в виде отдельных backend-микросервисов. За это время мы выучили REST API Б24, пожалуй, наизусть и параллельно следили за развитием инструментов работы ИИ-моделей с внешним миром.
Нас заинтересовал Model Context Protocol (MCP), разработанный Anthropic, сразу же, как он появился. Тогда, пожалуй, у всех были сомнения в том, станет ли он отраслевым стандартом. Сделать и выложить в открытый доступ MCP‑сервер для Б24 мы решили, когда увидели рост релизов MCP для топовых мировых сервисов этой весной, и для многих неожиданную поддержку MCP от главных конкурентов Anthropic — OpenAI.
Что же новое дает MCP бизнесу? Представьте, если бы вы могли спросить у ИИ‑ассистента: «Найди все контакты из компании «ТехноСтрой», у которых не было сделок в этом году» или «Подготовь сводку по активным сделкам менеджера Иванова на сумму свыше 500 000 рублей». Получить на них точные ответы и даже увидеть сформированные графики.
Именно с такими вопросами и позволяет работать MCP-сервер — «мост», который позволяет использовать функции и данные Битрикс24 как предопределенные «инструменты» и «ресурсы», которыми дирижирует ИИ.
Сервер уже опубликован на нашем GitHub, и мы активно приглашаем сообщество к его развитию:
https://github.com/kartochka/bitrix24-mcp
Зачем LLM для работы c данными Битрикс24 нужен MCP?
Model Context Protocol (MCP) — это развивающийся стандарт, призванный унифицировать передачу контекста в LLM из внешних ресурсов. Для своей задачи он лучше, чем обычный API:
Безопасность: Вы четко контролируете, какие именно действия (Инструменты) и данные (Ресурсы) доступны LLM. Никаких случайных удалений или доступа к нежелательным данным.
Простота для ИИ: LLM проще оперировать высокоуровневыми, понятными по смыслу командами (вроде
search_contacts_by_phone) и ресурсами (deal://456), чем разбираться в сотнях методов REST API и их параметрах.Стандартизация и совместимость: Клиенты, поддерживающие MCP (Claude Desktop, Cursor, Cline и другие), могут автоматически обнаруживать и использовать возможности сервера без дополнительной настройки под конкретные инструменты.
Абстракция и обработка: сервер берет на себя «грязную» работу: преобразование типов данных (особенно дат), обработку ошибок и особенностей API Б24, форматирование ответов для лучшего понимания моделью.
По сути, этот MCP-сервер — это умный и безопасный переводчик между миром LLM и вашим порталом Битрикс24.
Что умеет сервер уже сейчас?
Текущая версия работает со следующими сущностями CRM:
Работа с Контактами:
Инструмент
get_contact(получает контакты из CRM поID)Инструмент
search_contacts(ищет контакты по имени, телефону, email)Инструмент
list_contacts(получает список контактов с базовой фильтрацией)Ресурс
contact://{contact_id}(URI для получения заранее подготовленной информации о контакте)
Работа со Сделками:
Инструмент
get_deal(получает сделку поID)Инструмент
list_deals(получает список, фильтрует по активным, контакту, компании)Ресурс
deal://{deal_id}(URI для получения готовых данных по конкретной сделке)Ресурс
deals://active(URI для получения списка всех активных сделок)
Немного о стеке
Мы постарались сделать код сервера понятным и легко расширяемым. Выбрали Python 3.12+ и асинхронный подход с API и LLM. Используем библиотеку fast-bitrix24 для взаимодействия с REST API Битрикс24, fastmcp для реализации самого MCP-сервера, а также structlog для структурированного логирования. Как менеджер пакетов взяли uv.
Как работает сервер
Давайте вернемся к нашему примеру:
Пользователь: "Проведи аналитику по сделкам за последний месяц. Сколько было успешных? С кем на стороне клиентов по ним работали? Покажи распределение по стадиям."
Запрос поступает в LLM, которая запускает наш MCP-сервер.
LLM анализирует запрос и метаданные доступных инструментов/ресурсов, предоставленные сервером (например,
list_dealsс описанием его параметров filter, select).LLM решает, что для ответа нужно вызвать инструмент
list_deals. Она формирует вызов:MCP -> Server: call(instrument="list_deals", params={"filter": {"DATE_CREATE": "last_month", "STAGE_SEMANTIC_ID": "S"}, "select": ["ID", "STAGE_ID", "CONTACT_ID"]})MCP-сервер получает запрос, валидирует параметры, транслирует его в корректный вызов
crm.deal.listAPI Б24.Битрикс24 возвращает список ID сделок, их стадий и ID контактов.
Сервер обрабатывает ответ Б24 (приводит типы, если нужно) и передает его LLM в структурированном виде.
LLM понимает, что ей нужны детали контактов. Она извлекает
CONTACT_ID из успешных сделок и генерирует серию вызовов get_contact: MCP -> Server: call(instrument="get_contact", params={"id": 123}), MCP -> Server: call(instrument="get_contact", params={"id": 456}), ...MCP-сервер выполняет запросы
crm.contact.getк Битрикс24, валидирует данные и передает LLM информацию о контактах (имена, телефоны и т.д.).LLM агрегирует все полученные данные, формирует понятный ответ пользователю — вплоть до того, что сразу же может создать по ним в Claude Desktop дашборд, используя Artifacts.
Вы видите, что MCP — не абстракция. Сервер понимает естественный язык, знает как правильно перевести его в запросы к порталу, чтобы получить нужные данные.
«Коллеги из «Карточки» создали отличное решение, которое уже сейчас может приносить реальную практическую пользу. Многие пользователи Битрикс24 наверняка мечтали просто «на человеческом» языке запросить нужные данные, а не корпеть над настройкой отчётов.
Это открывает новые возможности для интеграторов: с помощью MCP‑сервера можно предложить клиентам по-настоящему гибкую автоматизацию. Остаётся только расширить набор ресурсов и инструментов платформы. Благодаря лицензии MIT партнёрское и разработческое сообщество Битрикс24 сможет быстро «нарастить мясо» на скелет, который вы уже сделали — и поделиться этим кодом выгодно для всех.
Большое спасибо команде «Карточки» за то, что сразу открыли свой продукт всем партнёрам и клиентам Битрикс24!»
— Сергей Востриков, руководитель направления Маркетплейс и интеграций Битрикс24
Как начать использовать MCP-сервер
Для подключения и настройки сервера понадобится не более 5 минут:
Клонируйте репо:
git clonehttps://github.com/kartochka/bitrix24-mcpДобавьте MCP-сервер в ваш клиент:
{ "mcpServers": { "Bitrix24 MCP Server": { "command": "uv", "args": [ "--directory", "полный_путь_до_проекта", "run", "main.py" ], "env": { "BITRIX_WEBHOOK_URL": "ваш_bitrix_token" } } }}
Готово! Теперь ваша LLM может работать с контактами и сделками вашего портала.
Давайте работать вместе!
MCP-сервер для Битрикс24 — это наш первый и пока единственный опенсорс-проект. Мы будем очень рады, если вы:
Попробуете сервер: Установите, попробуете на своих тестовых порталах, сообщите об ошибках или неудобствах в GitHub Issues.
Предложите идеи: Каких Инструментов или Ресурсов вам не хватает в первую очередь? Создайте Issue с предложением!
Поможете с кодом:
Для новичков: Реализуйте простой инструмент, например,
get_companyпоID(по аналогии сget_contact). Мы подготовили архитектуру так, чтобы добавление было максимально простым (скопировать класс, добавить модели, зарегистрировать инструмент).Добавьте поддержку нового модуля (Смарт-процессы, Лиды, Задачи).
Реализуйте методы создания/обновления для Контактов или Сделок.
Напишете тесты: Помогите повысить стабильность, написав тесты для существующих сервисов.
Улучшите документацию: Чтобы
READMEи примеры были еще понятнее.
Присоединяйтесь к нам в GitHub Discussions для обсуждения идей и планов.
