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 для управления зависимостями.
• Конфигурируемость: Настройки управляются через переменные окружения или .env файл (pydantic-settings).
• Структурированное Логирование: Использует structlog для удобного отслеживания событий.
• Расширяемость: Легко добавлять поддержку новых сущностей Bitrix24 или новые MCP инструменты/ресурсы.

Технологии

• Python 3.12+
• Fast-Bitrix24: Клиент для Bitrix24 REST API
• MCP (Model Context Protocol): Фреймворк для создания MCP серверов (fastmcp)
• WireUp: Контейнер внедрения зависимостей
• Pydantic & Pydantic-Settings: Валидация данных и управление настройками
• Structlog: Структурированное логирование
• Ruff: Линтер и форматер кода
• Asyncio

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

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

1. Python: Версия 3.12 или выше.
2. Bitrix24:
   • Аккаунт Bitrix24 (облачный или коробочный).
   • Входящий вебхук (Webhook) с необходимыми правами (как минимум crm). Как создать вебхук.

Установка

1. Клонируйте репозиторий:

   git clone https://github.com/kartochka/bitrix24-mcp.git
   cd mcp-server-b24
   

2. Создайте и активируйте виртуальное окружение:

   uv sync --no-dev
   

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

Серверу требуется URL вашего вебхука Bitrix24. Его можно задать одним из способов:

1. Переменная окружения:

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

2. Файл .env: Создайте файл .env в корневой директории проекта со следующим содержимым:

   # .env
   BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/yoursecretcode/"
   
   # Опциональный уровень логирования (DEBUG, INFO, WARNING, ERROR, CRITICAL)
   # LOG_LEVEL=INFO
   

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

После установки и настройки, запустите MCP сервер:

python main.py
# или если вы установили пакет глобально или через pip install .
mcp-server-b24

Вы увидите логи в консоли, включая информацию о зарегистрированных 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 для подробностей.