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-утилиты для управления зависимостями и скриптами
Начало Работы
Предварительные Требования
- Python: Версия 3.12 или выше.
- 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 - Возвращает: Текстовое представление списка активных сделок.
Разработка и Участие
Мы приветствуем контрибьюторов!
Настройка Среды Разработки
- Выполните шаги из раздела Установка.
- Установите зависимости для разработки:
uv sync
Качество Кода
- Форматирование и Линтинг: Используется
ruff. Перед коммитом рекомендуется запускать:ruff format . ruff check . --fix
- Типизация: Проект использует строгую типизацию Python.
Процесс Внесения Изменений
- Создайте Issue: Опишите проблему или предлагаемое улучшение в разделе Issues репозитория.
- Форкните репозиторий: Создайте свою копию проекта.
- Создайте ветку:
git checkout -b feature/your-feature-nameилиbugfix/issue-number. - Внесите изменения: Напишите код и тесты (если применимо).
- Проверьте качество кода: Запустите
ruff. - Сделайте коммит:
git commit -m "feat: Add support for Bitrix24 Leads"(следуйте Conventional Commits если возможно). - Отправьте изменения в ваш форк:
git push origin feature/your-feature-name. - Создайте Pull Request: Откройте Pull Request из вашей ветки в
mainветку основного репозитория. Опишите внесенные изменения и свяжите PR с созданным Issue.
Лицензия
Этот проект лицензирован под лицензией MIT — см. файл LICENSE для подробностей.
Metadata
Release files for iflow-mcp_kartochka-bitrix24-mcp 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_kartochka_bitrix24_mcp-1.0.1.tar.gz | 67.5 kB | Without provenance | Details for iflow_mcp_kartochka_bitrix24_mcp-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_kartochka_bitrix24_mcp-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_kartochka_bitrix24_mcp-1.0.1-py3-none-any.whl |
Total release size: 115.7 kB
Release files / iflow_mcp_kartochka_bitrix24_mcp-1.0.1.tar.gz
| Download URL | iflow_mcp_kartochka_bitrix24_mcp-1.0.1.tar.gz |
|---|---|
| Size | 67.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
afedfd480f9c56773e87c80cfe98280f387228abb24156b687f9bb9dda8cfa7f
|
|
BLAKE2b-256 checksum How to use checksums |
28cbf3904654a19c86b98f6bc7db1dfca9cd1af1644f8aa5f402268f67e5dfc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_kartochka_bitrix24_mcp-1.0.1-py3-none-any.whl
| Download URL | iflow_mcp_kartochka_bitrix24_mcp-1.0.1-py3-none-any.whl |
|---|---|
| Size | 48.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67a45bb3e9d5b3e9bc9c3e89948624a69ccc4f898fb4ea40798a7b7b398d7ad6
|
|
BLAKE2b-256 checksum How to use checksums |
04e7e6355d7893c6e0ef04fd76a12b0de4c517f7e1af50efc7a86ba9591790c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_kartochka-bitrix24-mcp 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.