Говорим с Битрикс24 на языке ИИ: представляем опенсорс MCP-сервер для LLM-интеграции

Привет! Мы — партнеры Битрикс24 и создаем для бизнеса приложения с генеративным ИИ, интегрируя их с корпоративными порталами.

В этой статье мы расскажем о созданном нами решении, которое позволяет любым разработчикам легко подключать свои чаты и другие приложения с LLM-моделями к Битрикс24. Речь идет о MCP-сервере — помощнике для ИИ, который позволяет получать из портала Битрикс24, например из раздела CRM, точные данные для ответа пользователю.

Почему мы вообще решили сделать MCP-сервер именно для Битрикс24? 

В «Карточке ^[1]» мы начали внедрять первые обработки данных генеративным ИИ в Битрикс24 в 2023 году, разворачивая их в виде отдельных backend-микросервисов. За это время мы выучили REST API Б24, пожалуй, наизусть и параллельно следили за развитием инструментов работы ИИ-моделей с внешним миром.

Нас заинтересовал Model Context Protocol (MCP), разработанный Anthropic, сразу же, как он появился ^[2]. Тогда, пожалуй, у всех были сомнения в том, станет ли он отраслевым стандартом. Сделать и выложить в открытый доступ MCP‑сервер для Б24 мы решили, когда увидели рост релизов MCP для топовых мировых сервисов этой весной, и для многих неожиданную поддержку MCP от главных конкурентов Anthropic — OpenAI ^[3].

Что же новое дает MCP бизнесу? Представьте, если бы вы могли спросить у ИИ‑ассистента: «Найди все контакты из компании «ТехноСтрой», у которых не было сделок в этом году» или «Подготовь сводку по активным сделкам менеджера Иванова на сумму свыше 500 000 рублей». Получить на них точные ответы и даже увидеть сформированные графики.

Именно с такими вопросами и позволяет работать MCP-сервер — «мост», который позволяет использовать функции и данные Битрикс24 как предопределенные «инструменты» и «ресурсы», которыми дирижирует ИИ.

Сервер уже опубликован на нашем GitHub, и мы активно приглашаем сообщество к его развитию:

https://github.com/kartochka/bitrix24-mcp ^[4]

Зачем LLM для работы c данными Битрикс24 нужен MCP?

Model Context Protocol (MCP) — это развивающийся стандарт, призванный унифицировать передачу контекста в LLM из внешних ресурсов. Для своей задачи он лучше, чем обычный API:

1. Безопасность: Вы четко контролируете, какие именно действия (Инструменты) и данные (Ресурсы) доступны LLM. Никаких случайных удалений или доступа к нежелательным данным.

2. Простота для ИИ: LLM проще оперировать высокоуровневыми, понятными по смыслу командами (вроде search_contacts_by_phone) и ресурсами (deal://456), чем разбираться в сотнях методов REST API и их параметрах.

3. Стандартизация и совместимость: Клиенты, поддерживающие MCP (Claude Desktop, Cursor, Cline и другие), могут автоматически обнаруживать и использовать возможности сервера без дополнительной настройки под конкретные инструменты.

4. Абстракция и обработка: сервер берет на себя «грязную» работу: преобразование типов данных (особенно дат), обработку ошибок и особенностей 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.

Как работает сервер

Давайте вернемся к нашему примеру:

Пользователь: “Проведи аналитику по сделкам за последний месяц. Сколько было успешных? С кем на стороне клиентов по ним работали? Покажи распределение по стадиям.”

1. Запрос поступает в LLM, которая запускает наш MCP-сервер.

2. LLM анализирует запрос и метаданные доступных инструментов/ресурсов, предоставленные сервером (например, list_deals с описанием его параметров filter, select).

3. 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"]})

4. MCP-сервер получает запрос, валидирует параметры, транслирует его в корректный вызов crm.deal.list API Б24.

5. Битрикс24 возвращает список ID сделок, их стадий и ID контактов.

6. Сервер обрабатывает ответ Б24 (приводит типы, если нужно) и передает его LLM в структурированном виде.

7. LLM понимает, что ей нужны детали контактов. Она извлекает CONTACT_ID из успешных сделок и генерирует серию вызовов get_contact: MCP -> Server: call(instrument="get_contact", params={"id": 123}), MCP -> Server: call(instrument="get_contact", params={"id": 456}), ...

8. MCP-сервер выполняет запросы crm.contact.get к Битрикс24, валидирует данные и передает LLM информацию о контактах (имена, телефоны и т.д.).

9. LLM агрегирует все полученные данные, формирует понятный ответ пользователю — вплоть до того, что сразу же может создать по ним в Claude Desktop дашборд, используя Artifacts.

Вы видите, что MCP — не абстракция. Сервер понимает естественный язык, знает как правильно перевести его в запросы к порталу, чтобы получить нужные данные.

«Коллеги из «Карточки» создали отличное решение, которое уже сейчас может приносить реальную практическую пользу. Многие пользователи Битрикс24 наверняка мечтали просто «на человеческом» языке запросить нужные данные, а не корпеть над настройкой отчётов. 

Это открывает новые возможности для интеграторов: с помощью MCP‑сервера можно предложить клиентам по-настоящему гибкую автоматизацию. Остаётся только расширить набор ресурсов и инструментов платформы. Благодаря лицензии MIT партнёрское и разработческое сообщество Битрикс24 сможет быстро «нарастить мясо» на скелет, который вы уже сделали — и поделиться этим кодом выгодно для всех.

Большое спасибо команде «Карточки» за то, что сразу открыли свой продукт всем партнёрам и клиентам Битрикс24!»

— Сергей Востриков, руководитель направления Маркетплейс и интеграций Битрикс24

Как начать использовать MCP-сервер

Для подключения и настройки сервера понадобится не более 5 минут: 

1. Клонируйте репо: git clonehttps://github.com/kartochka/bitrix24-mcp ^[4]

2. Добавьте MCP-сервер в ваш клиент: 

{
  "mcpServers": {
    "Bitrix24 MCP Server": {
      "command": "uv",
      "args": [
        "--directory",
        "полный_путь_до_проекта",
        "run",
        "main.py"
      ],
      "env": {
        "BITRIX_WEBHOOK_URL": "ваш_bitrix_token"
      }
    }
  }
}

Готово! Теперь ваша LLM может работать с контактами и сделками вашего портала.

Давайте работать вместе!

MCP-сервер для Битрикс24 ^[4] — это наш первый и пока единственный опенсорс-проект. Мы будем очень рады, если вы:

• Попробуете сервер: Установите, попробуете на своих тестовых порталах, сообщите об ошибках или неудобствах в GitHub Issues ^[5].

• Предложите идеи: Каких Инструментов или Ресурсов вам не хватает в первую очередь? Создайте Issue с предложением!

• Поможете с кодом:

  • Для новичков: Реализуйте простой инструмент, например, get_company по ID (по аналогии с get_contact). Мы подготовили архитектуру так, чтобы добавление было максимально простым (скопировать класс, добавить модели, зарегистрировать инструмент). 

  • Добавьте поддержку нового модуля (Смарт-процессы, Лиды, Задачи).

  • Реализуйте методы создания/обновления для Контактов или Сделок.

• Напишете тесты: Помогите повысить стабильность, написав тесты для существующих сервисов.

• Улучшите документацию: Чтобы README и примеры были еще понятнее.

Присоединяйтесь к нам в GitHub Discussions ^[6] для обсуждения идей и планов.