iflow-mcp_kartochka-bitrix24-mcp 1.0.1

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 для управления зависимостями.
• Конфигурируемость: Настройки управляются через переменные окружения.
• Структурированное Логирование: Использует 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 для подробностей.