bitrix24-mcp 1.0.0

MCP server for interacting with Bitrix24 using natural language and AI dialogues to get data, perform actions, and manage the system.

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 для подробностей.