Bitrix24 MCP Server

Интеграционный сервер, использующий Model Context Protocol (MCP), для предоставления доступа к данным и функциям Bitrix24 для больших языковых моделей (LLM) и других AI-агентов. LLM могут безопасно взаимодействовать с вашими CRM-данными (контакты, сделки), используя предопределенные "инструменты" и "ресурсы", предоставляемые этим сервером через стандартный протокол MCP.

Ключевые Особенности

• Интеграция с Bitrix24: Доступ к контактам и сделкам через Bitrix24 REST API.

• Model Context Protocol (MCP): Предоставляет стандартизированный интерфейс для взаимодействия с AI-моделями.

  • Инструменты (Tools): Функции, которые AI может вызывать (например, поиск контактов, обновление стадии сделки).

  • Ресурсы (Resources): Данные, которые AI может запрашивать (например, информация о конкретном контакте или список активных сделок).

  • Промпты (Prompts): Шаблоны для генерации запросов к AI.

• Асинхронность: Построен на asyncio для эффективной обработки запросов.

• Внедрение Зависимостей: Использует wireup для управления зависимостями.

• Конфигурируемость: Настройки управляются через переменные окружения.

• Структурированное Логирование: Использует structlog для удобного отслеживания событий.

• Расширяемость: Легко добавлять поддержку новых сущностей Bitrix24 или новые MCP инструменты/ресурсы.

Технологии

• Python 3.12+

• Fast-Bitrix24: Клиент для Bitrix24 REST API

• MCP (Model Context Protocol): Фреймворк для создания MCP серверов (fastmcp)

• Pydantic & Pydantic-Settings: Валидация данных и управление настройками

• Structlog: Структурированное логирование

• Ruff: Линтер и форматер кода

• Asyncio

• Dishka: CLI-утилиты для управления зависимостями и скриптами

Начало Работы

Предварительные Требования

1. Python: Версия 3.12 или выше.

2. Bitrix24:

   • Аккаунт Bitrix24 (облачный или коробочный).

   • Входящий вебхук (Webhook) с необходимыми правами (как минимум crm). Как создать вебхук.

Конфигурация

Серверу требуется задать переменную окружения BITRIX_WEBHOOK_URL:

export BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/yoursecretcode/"

Запуск Сервера

запустите MCP сервер:

uvx bitrix24-mcp

Вы увидите логи в консоли, включая информацию о зарегистрированных MCP инструментах и ресурсах.

Запуск Тестового Скрипта

Для проверки базовой работоспособности интеграции с Bitrix24 API можно запустить тестовый скрипт:

python test_services.py

Скрипт выполнит несколько запросов к API Bitrix24 (получение списка контактов, получение контакта по ID, и т.д.) и выведет результаты.

Использование

Запущенный MCP сервер готов принимать запросы от MCP-совместимых клиентов или LLM.

Доступные MCP Инструменты (Tools)

Инструменты - это функции, которые AI может попросить выполнить.

• tool://get_contact

  • Описание: Получение информации о контакте по ID.

  • Параметры: contact_id: int

  • Возвращает: JSON-строка с данными контакта.

• tool://search_contacts

  • Описание: Поиск контактов по имени, телефону или email.

  • Параметры: query: str, search_type: str = "name" (name, phone, email), limit: int = 10

  • Возвращает: JSON-строка со списком найденных контактов.

• tool://list_contacts

  • Описание: Получение списка контактов с возможностью фильтрации.

  • Параметры: limit: int = 50, company_id: int | None = None

  • Возвращает: JSON-строка со списком контактов.

• tool://get_deal

  • Описание: Получение информации о сделке по ID.

  • Параметры: deal_id: int

  • Возвращает: JSON-строка с данными сделки.

• tool://list_deals

  • Описание: Получение списка сделок с возможностью фильтрации.

  • Параметры: active_only: bool = False, contact_id: int | None = None, company_id: int | None = None, limit: int = 50

  • Возвращает: JSON-строка со списком сделок.

• tool://update_deal_stage

  • Описание: Обновление стадии сделки.

  • Параметры: deal_id: int, stage_id: str (например, C14:WON)

  • Возвращает: JSON-строка с результатом операции ({"success": true/false, "message": "..."}).

Доступные MCP Ресурсы (Resources)

Ресурсы - это данные, которые AI может запросить по URI.

• contact://{contact_id}

  • Описание: Получение данных контакта по ID в читаемом формате.

  • Пример: contact://123

  • Возвращает: Текстовое представление данных контакта.

• deal://{deal_id}

  • Описание: Получение данных сделки по ID в читаемом формате.

  • Пример: deal://456

  • Возвращает: Текстовое представление данных сделки.

• deals://active

  • Описание: Получение списка активных сделок в читаемом формате.

  • Пример: deals://active

  • Возвращает: Текстовое представление списка активных сделок.

Разработка и Участие

Мы приветствуем контрибьюторов!

Настройка Среды Разработки

1. Выполните шаги из раздела Установка.

2. Установите зависимости для разработки:

   uv sync

Качество Кода

• Форматирование и Линтинг: Используется ruff. Перед коммитом рекомендуется запускать:

  ruff format .
  ruff check . --fix

• Типизация: Проект использует строгую типизацию Python.

Процесс Внесения Изменений

1. Создайте Issue: Опишите проблему или предлагаемое улучшение в разделе Issues репозитория.

2. Форкните репозиторий: Создайте свою копию проекта.

3. Создайте ветку: git checkout -b feature/your-feature-name или bugfix/issue-number.

4. Внесите изменения: Напишите код и тесты (если применимо).

5. Проверьте качество кода: Запустите ruff.

6. Сделайте коммит: git commit -m "feat: Add support for Bitrix24 Leads" (следуйте Conventional Commits если возможно).

7. Отправьте изменения в ваш форк: git push origin feature/your-feature-name.

8. Создайте Pull Request: Откройте Pull Request из вашей ветки в main ветку основного репозитория. Опишите внесенные изменения и свяжите PR с созданным Issue.

Лицензия

Этот проект лицензирован под лицензией MIT — см. файл LICENSE для подробностей.