Bitrix24 MCP с локальным кешем CRM
bitrix24mcp
MCP-сервер Битрикс24, который держит копию CRM в PostgreSQL или SQLite и отвечает агенту из кеша, а не с каждым запросом к REST
Высокий риск
Высокий уровень ставим, когда инструмент пишет во внешние системы, работает с деньгами, рабочими базами или секретами либо выполняет произвольные команды. CLI поставит его только после вашего согласия.
Почему такой уровень
- Создает контакты, сделки и лиды и меняет стадии сделок в реальном портале
- Хранит копию данных CRM, включая клиентские, в собственной локальной базе
Установка
Ручная установка
pip install -e ".[webhook]"Установка с поддержкой вебхуков реального времени, для только MCP-сервера достаточно pip install -e .
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Сервер синхронизирует контакты, компании, сделки, лиды, воронки, стадии и ленту активностей из Битрикс24 в локальную базу и обслуживает чтение агента из этого кеша: поиск и карточки по всем CRM-сущностям, список воронок и стадий конкретной воронки, агрегированную сводку по клиенту и ленту событий CRM, а также отчет по портфелю сделок. Записи (создание контакта, сделки, лида, смена стадии, комментарий в ленту) уходят в Битрикс24 напрямую, а затем обновляют локальный кеш. Авторизация двумя способами: OAuth2 со всплывающим окном входа Битрикс24, который сам получает и хранит токены, либо входящий вебхук без регистрации приложения. Есть опциональный HTTP-обработчик вебхуков реального времени на события изменения контактов, компаний, сделок и лидов, чтобы кеш обновлялся мгновенно, а не только по ручной синхронизации.
Для кого. Для команд с большой CRM-базой, которым важны скорость ответа агента и агрегированные отчеты.
Подходит, если
- Нужна быстрая агрегированная сводка по клиенту или отчет по портфелю сделок без множества запросов к REST
- Нужны мгновенные обновления кеша через вебхуки реального времени
- Нужен выбор между OAuth2 с окном входа и простым вебхуком по ситуации
Не подходит, если
- Не готовы держать локальную базу (PostgreSQL или SQLite) и следить за ее свежестью
- Нужны только свежайшие данные без кеша: TTL кеша может давать чуть устаревший ответ между синхронизациями
Пример запроса к агенту
Покажи агрегированную сводку по клиенту Иванов: сделки, активности и текущий отчет по портфелюОграничения
Чтение обслуживается из локального кеша, а не напрямую из Битрикс24, поэтому между синхронизациями данные могут немного отставать, свежесть определяется настройкой CACHE_TTL. Для мгновенных обновлений нужен отдельный процесс HTTP-обработчика вебхуков и регистрация событий в Битрикс24 на его адрес. Первичная синхронизация sync_crm_data нужна перед первым использованием.
Как отключить. Остановите сервер и обработчик вебхуков, удалите файл базы SQLite или базу PostgreSQL и отзовите вебхук или OAuth-приложение в портале.
MCP
- Транспорт
- stdio
- Авторизация
- API-ключ
| Переменные окружения | |
|---|---|
| BITRIX24_WEBHOOK_URL секрет | URL входящего вебхука, альтернатива OAuth2 |
| BITRIX24_CLIENT_ID секрет | ID серверного приложения Битрикс24 для OAuth2 |
| DATABASE_URL обязательная | Строка подключения к локальной базе кеша, SQLite или PostgreSQL |
Проверка безопасности
- Создает контакты, сделки и лиды и меняет стадии сделок в реальном портале
- Хранит копию данных CRM, включая клиентские, в собственной локальной базе
Коротко о README
README описывает кеширующую архитектуру (REST API, локальная база, MCP-инструменты, агент), структуру пакета по модулям, таблицу из девятнадцати инструментов по CRM и отчетам, установку через pip с опциональной поддержкой вебхуков, два способа авторизации с пошаговыми инструкциями, поднятие PostgreSQL через Docker Compose, запуск сервера, проверку статуса авторизации, первичную синхронизацию, настройку вебхуков реального времени, конфигурации для Claude Desktop и схему базы данных с принципом работы чтения из кеша и записи напрямую в Битрикс24.
Частые вопросы
Какой способ авторизации проще?
Входящий вебхук: не нужно регистрировать приложение, достаточно создать вебхук в разделе Разработчикам и вписать его URL.
Как кеш узнает об изменениях в реальном времени?
Через отдельный uvicorn-обработчик на порту 8080, зарегистрированный в Битрикс24 на события onCrmDealAdd, onCrmContactUpdate и подобные.
Похожие
Официальный MCP-сервер Salesforce DX: работа с org, метаданными, данными, пользователями и тестами Apex из агента
Официальный набор скиллов Яндекса: каталог, цены, остатки, заказы, витрина и еженедельная ревизия магазина на Яндекс.Кит через Claude Code или Codex
YouGile MCP от Indalo
YouGile MCP
Полное покрытие API YouGile из 65 операций с настраиваемыми правами, подтверждением записи и общим лимитом на компанию
Официальный MCP конкретного портала Битрикс24: внешний агент по OAuth или токену читает и меняет задачи, сделки, встречи и письма