Content
# Bitrix24 MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/release/python-3120/)
[](https://github.com/astral-sh/ruff)
Интеграционный сервер, использующий 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](https://github.com/leshchenko1979/fast_bitrix24): Клиент для Bitrix24 REST API
* [MCP (Model Context Protocol)](https://github.com/mentalcalculation/mcp): Фреймворк для создания MCP серверов (`fastmcp`)
* [Pydantic & Pydantic-Settings](https://docs.pydantic.dev/): Валидация данных и управление настройками
* [Structlog](https://www.structlog.org/): Структурированное логирование
* [Ruff](https://github.com/astral-sh/ruff): Линтер и форматер кода
* Asyncio
* [Dishka](https://pypi.org/project/dishka/): CLI-утилиты для управления зависимостями и скриптами
## Начало Работы
### Предварительные Требования
1. **Python:** Версия 3.12 или выше.
2. **Bitrix24:**
* Аккаунт Bitrix24 (облачный или коробочный).
* Входящий вебхук (Webhook) с необходимыми правами (как минимум `crm`). [Как создать вебхук](https://helpdesk.bitrix24.ru/open/20886106/).
### Конфигурация
Серверу требуется задать переменную окружения `BITRIX_WEBHOOK_URL`:
```bash
export BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/yoursecretcode/"
```
### Запуск Сервера
запустите MCP сервер:
```bash
uvx bitrix24-mcp
```
Вы увидите логи в консоли, включая информацию о зарегистрированных MCP инструментах и ресурсах.
### Запуск Тестового Скрипта
Для проверки базовой работоспособности интеграции с Bitrix24 API можно запустить тестовый скрипт:
```bash
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. Установите зависимости для разработки:
```bash
uv sync
```
### Качество Кода
* **Форматирование и Линтинг:** Используется `ruff`. Перед коммитом рекомендуется запускать:
```bash
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](https://www.conventionalcommits.org/) если возможно).
7. **Отправьте изменения в ваш форк:** `git push origin feature/your-feature-name`.
8. **Создайте Pull Request:** Откройте Pull Request из вашей ветки в `main` ветку основного репозитория. Опишите внесенные изменения и свяжите PR с созданным Issue.
## Лицензия
Этот проект лицензирован под лицензией MIT — см. файл [LICENSE](LICENSE) для подробностей.
