MCP 服务器

Bitrix24 MCP Server

Enables AI agents to interact with Bitrix24 CRM through standardized MCP tools, including searching and managing contacts, deals, leads, tasks, and replying in chats.

README

Bitrix24 MCP Server

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, или любой хостинг) для приёма вебхуков