Bitrix24 MCP Server

License: MIT Python 3.12+ MCP

MCP-сервер для Bitrix24 CRM: подключите AI-агента к сделкам, контактам и чатам за 5 минут.

Bitrix24 MCP Server предоставляет стандартизированный Model Context Protocol интерфейс, через который любой AI-агент (Claude, GPT, DeepSeek, локальные LLM) может:

🔍 Искать контакты, сделки, лиды
📝 Создавать и обновлять CRM-сущности
💬 Отвечать в чатах Bitrix24 как обычный сотрудник
📋 Писать комментарии в таймлайн сделок

Всё через единый протокол. Без написания REST-обёрток. Без парсинга вебхуков. Один раз настроил — и забыл.

Быстрый старт (5 минут)

1. Установка

pip install bitrix24-mcp

2. Настройка

Создайте входящий вебхук в Bitrix24 (права: crm, imbot, user) и пропишите URL:

export BITRIX_WEBHOOK_URL="https://your.bitrix24.ru/rest/1/your-token/"

3. Запуск

bitrix24-mcp

Готово. Сервер слушает stdio — можно подключать AI-клиент (Claude Desktop, Cursor, Hermes Agent).

Подключение AI-агента к чатам Bitrix24

Сервер включает готовый слой для чат-ботов (imbot):

from src.domain.entities.bot_event import BotIncomingMessage, BotReply
from src.application.services.chat_bot import ChatBotService

class MyAIAgent:
    """Ваш AI-агент. Единственное, что нужно написать."""

    async def handle_message(self, message: BotIncomingMessage) -> BotReply:
        # Вызовите свою LLM
        answer = await my_llm.ask(message.text)
        return BotReply(
            text=answer,
            # Опционально: дублировать в таймлайн сделки
            timeline_comment=TimelineCommentTarget(
                entity_type="deal",
                entity_id=123
            )
        )

# Регистрация — остальное сервер берёт на себя
chat_bot_service.register_agent(bot_id, MyAIAgent())

После регистрации ваш AI-агент появляется в общих чатах Bitrix24 как обычный сотрудник. Менеджер пишет — агент отвечает. Комментарии автоматически попадают в таймлайн.

MCP-инструменты

CRM: Контакты

Инструмент	Описание
`get_contact`	Получить контакт по ID
`search_contacts`	Поиск по имени, телефону, email
`list_contacts`	Список с фильтрацией

CRM: Сделки

Инструмент	Описание
`get_deal`	Сделка по ID
`list_deals`	Список с фильтрами (активные, по контакту)
`update_deal_stage`	Передвинуть сделку по воронке
`create_deal`	Создать новую сделку

CRM: Лиды

Инструмент	Описание
`create_lead`	Создать лид
`list_leads`	Список с поиском
`get_lead`	Лид по ID

Чат-бот

Инструмент	Описание
`ChatBotService.register_bot`	Зарегистрировать бота в портале
`ChatBotService.register_agent`	Подключить AI-агента к боту
`ChatBotService.dispatch_event`	Обработка входящих сообщений

Задачи

Инструмент	Описание
`search_tasks`	Поиск задач
`create_task`	Создать задачу
`get_task_by_id`	Задача по ID

MCP-ресурсы

AI-агент может запрашивать данные по URI:

Ресурс	Пример	Назначение
`contact://{id}`	`contact://123`	Данные контакта
`deal://{id}`	`deal://456`	Данные сделки
`deals://active`	`deals://active`	Все активные сделки

Подключение к AI-клиентам

Claude Desktop

{
  "mcpServers": {
    "bitrix24": {
      "command": "bitrix24-mcp",
      "env": {
        "BITRIX_WEBHOOK_URL": "https://your.bitrix24.ru/rest/1/token/"
      }
    }
  }
}

Hermes Agent

mcp_servers:
  bitrix24:
    transport: stdio
    command: bitrix24-mcp
    env:
      BITRIX_WEBHOOK_URL: "https://your.bitrix24.ru/rest/1/token/"

Cursor / VS Code

Добавьте в .cursor/mcp.json или настройки Cursor MCP.

Чат-бот: полный пример

export BOT_EVENT_HANDLER_URL="https://your-domain.example.com/bot/events"
python examples/custom_agent_example.py

Сервер регистрирует бота, поднимает HTTP-обработчик вебхуков и подключает AI-агента. Подробнее: docs/source/ai_chat_agent.rst.

Архитектура

AI-клиент (Claude/DeepSeek/GPT)
        │
        ▼ MCP (stdio)
┌───────────────────────┐
│  Bitrix24 MCP Server  │
│                       │
│  ┌─────────────────┐  │
│  │  MCP Handlers   │  │  ← CRM: contacts, deals, leads
│  ├─────────────────┤  │
│  │  ChatBotService │  │  ← imbot: register, dispatch, reply
│  ├─────────────────┤  │
│  │  WebhookServer  │  │  ← HTTP: приём событий Bitrix24
│  └─────────────────┘  │
└───────────┬───────────┘
            │ REST API (fast_bitrix24)
            ▼
     Bitrix24 Cloud

Требования

Python 3.12+
Входящий вебхук Bitrix24 (права: crm, imbot, user)
Для чат-бота: публичный HTTPS URL (ngrok, cloudflared, или любой хостинг) для приёма вебхуков

Лицензия

MIT. Подробности в LICENSE.