Bitrix24_MCP_Server

Bitrix24_MCP_Server

3
developer_toolscommunication

Bitrix24 MCP Server is a server application offering a REST API for Bitrix24 CRM interaction using the MCP architecture. It allows full access to CRM entities, supports client-side data formatting, and includes logging and error handling capabilities.

Bitrix24 MCP Server

Обзор

Bitrix24 MCP (Model-Controller-Presenter) Server - это серверное приложение, предоставляющее REST API для взаимодействия с Bitrix24 CRM. Сервер использует архитектурный паттерн MCP для организации кода и обеспечения четкого разделения ответственности между компонентами.

Особенности

  • Полный доступ к основным сущностям Bitrix24 CRM (сделки, лиды, контакты, задачи и т.д.)
  • Форматирование данных для удобного использования на клиентской стороне
  • Логирование запросов и ответов
  • Обработка ошибок и исключений
  • CORS поддержка для взаимодействия с фронтенд-приложениями

Требования

  • Node.js (версия 14.x или выше)
  • npm (версия 6.x или выше)
  • Доступ к Bitrix24 с настроенным webhook

Установка

  1. Клонируйте репозиторий:
git clone https://github.com/your-username/bitrix24-mcp-server.git
cd bitrix24-mcp-server
  1. Установите зависимости:
npm install
  1. Создайте файл .env в корневой директории проекта со следующими параметрами:
PORT=3000
BITRIX_DOMAIN=your-domain.bitrix24.ru
BITRIX_WEBHOOK_TOKEN=your-webhook-token
LOG_LEVEL=info
  1. Запустите сервер:
npm start

Архитектура

Сервер построен на основе архитектурного паттерна MCP (Model-Controller-Presenter):

  • Model (Bitrix24Model): Отвечает за взаимодействие с API Bitrix24 и обработку данных.
  • Controller (Bitrix24Controller): Обрабатывает HTTP-запросы, применяет бизнес-логику и координирует работу модели и презентера.
  • Presenter (Bitrix24Presenter): Форматирует данные для представления клиенту.

API Endpoints

Задачи

  • GET /api/tasks - Получение списка задач
    • Query параметры:
      • filter - JSON-строка с фильтрами (опционально)

Контакты

  • GET /api/contacts - Получение списка контактов
    • Query параметры:
      • filter - JSON-строка с фильтрами (опционально)

Сделки

  • GET /api/deals - Получение списка сделок
    • Query параметры:
      • filter - JSON-строка с фильтрами (опционально)
  • GET /api/deals/:id - Получение сделки по ID
  • POST /api/deals - Создание новой сделки
    • Body: объект с данными сделки
  • PUT /api/deals/:id - Обновление сделки
    • Body: объект с данными для обновления
  • GET /api/deal-categories - Получение воронок продаж
  • GET /api/deal-stages/:categoryId? - Получение стадий сделок для указанной воронки

Лиды

  • GET /api/leads - Получение списка лидов
    • Query параметры:
      • filter - JSON-строка с фильтрами (опционально)
  • GET /api/leads/:id - Получение лида по ID
  • POST /api/leads - Создание нового лида
    • Body: объект с данными лида
  • PUT /api/leads/:id - Обновление лида
    • Body: объект с данными для обновления
  • GET /api/lead-statuses - Получение статусов лидов

Активности (дела)

  • GET /api/activities - Получение списка активностей
    • Query параметры:
      • filter - JSON-строка с фильтрами (опционально)
  • GET /api/activities/:id - Получение активности по ID
  • POST /api/activities - Создание новой активности
    • Body: объект с данными активности
  • PUT /api/activities/:id - Обновление активности
    • Body: объект с данными для обновления

Пользователи

  • GET /api/users - Получение списка пользователей
    • Query параметры:
      • filter - JSON-строка с фильтрами (опционально)
  • GET /api/users/:id - Получение пользователя по ID

Таймлайн

  • POST /api/timeline-comment/:entityType/:entityId - Добавление комментария в таймлайн
    • Body: { "comment": "Текст комментария" }

Телефония

  • GET /api/call-statistics - Получение статистики звонков
    • Query параметры:
      • filter - JSON-строка с фильтрами (опционально)

Файлы

  • GET /api/files/:id - Получение информации о файле
  • GET /api/files/:id/download - Скачивание файла

Примеры использования

Получение списка сделок

// Клиентский код
async function getDeals() {
  try {
    const response = await fetch('http://localhost:3000/api/deals');
    const data = await response.json();
    console.log(data.deals);
  } catch (error) {
    console.error('Ошибка при получении сделок:', error);
  }
}

Создание нового лида

// Клиентский код
async function createLead() {
  try {
    const leadData = {
      TITLE: 'Новый лид с сайта',
      NAME: 'Иван',
      LAST_NAME: 'Иванов',
      STATUS_ID: 'NEW',
      PHONE: [{ VALUE_TYPE: 'WORK', VALUE: '+7 (999) 123-45-67' }],
      EMAIL: [{ VALUE_TYPE: 'WORK', VALUE: 'ivan@example.com' }]
    };
    
    const response = await fetch('http://localhost:3000/api/leads', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(leadData)
    });
    
    const result = await response.json();
    console.log('Лид создан:', result);
  } catch (error) {
    console.error('Ошибка при создании лида:', error);
  }
}

Обновление сделки

// Клиентский код
async function updateDeal(dealId, stageId) {
  try {
    const dealData = {
      STAGE_ID: stageId
    };
    
    const response = await fetch(`http://localhost:3000/api/deals/${dealId}`, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(dealData)
    });
    
    const result = await response.json();
    console.log('Сделка обновлена:', result);
  } catch (error) {
    console.error('Ошибка при обновлении сделки:', error);
  }
}

Логирование

Сервер использует встроенный механизм логирования для отслеживания запросов и ответов. Уровень логирования можно настроить в файле .env с помощью параметра LOG_LEVEL.

Доступные уровни логирования:

  • error - только ошибки
  • warn - предупреждения и ошибки
  • info - информационные сообщения, предупреждения и ошибки (по умолчанию)
  • debug - отладочная информация и все вышеперечисленное

Обработка ошибок

Сервер обрабатывает ошибки и возвращает соответствующие HTTP-статусы и сообщения:

  • 400 Bad Request - неверный формат запроса
  • 404 Not Found - ресурс не найден
  • 500 Internal Server Error - внутренняя ошибка сервера

Пример ответа с ошибкой:

{
  "error": "Ошибка при получении данных из Bitrix24 API"
}

Безопасность

  • Используйте HTTPS для защиты данных при передаче
  • Храните webhook-токен в безопасном месте и не включайте его в код
  • Регулярно обновляйте webhook-токен для минимизации рисков

Лицензия

MIT

MCP Сервер (mcp-server.js)

Обзор

mcp-server.js - это реализация MCP (Model Context Protocol) сервера для Bitrix24, который предоставляет набор инструментов для взаимодействия с Bitrix24 API через REST API сервер. MCP сервер работает как промежуточный слой между языковой моделью (LLM) и REST API сервером Bitrix24, позволяя языковой модели выполнять операции с данными Bitrix24 через структурированные инструменты.

Принцип работы

MCP сервер использует библиотеку @modelcontextprotocol/sdk для создания и регистрации инструментов, которые могут быть вызваны языковой моделью. Каждый инструмент представляет собой функцию, которая:

  1. Принимает параметры, определенные с помощью схемы Zod
  2. Выполняет запрос к REST API серверу Bitrix24
  3. Возвращает результат в структурированном формате

MCP сервер запускается через stdio транспорт, что позволяет ему взаимодействовать с языковой моделью через стандартные потоки ввода/вывода.

Доступные инструменты

MCP сервер предоставляет следующие группы инструментов:

Лиды
  • getLeads - получение списка лидов с возможностью фильтрации
  • getLead - получение информации о конкретном лиде по ID
  • createLead - создание нового лида
  • updateLead - обновление существующего лида
  • getLeadStatuses - получение списка статусов лидов
Сделки
  • getDeals - получение списка сделок с возможностью фильтрации
  • getDeal - получение информации о конкретной сделке по ID
  • createDeal - создание новой сделки
  • updateDeal - обновление существующей сделки
  • getDealCategories - получение списка воронок продаж
  • getDealStages - получение списка стадий сделок для указанной воронки
Контакты
  • getContacts - получение списка контактов с возможностью фильтрации
  • getContact - получение информации о конкретном контакте по ID
Активности
  • getActivities - получение списка активностей с возможностью фильтрации
  • getActivity - получение информации о конкретной активности по ID
  • createActivity - создание новой активности
  • updateActivity - обновление существующей активности
Пользователи
  • getUsers - получение списка пользователей с возможностью фильтрации
  • getUser - получение информации о конкретном пользователе по ID
Задачи
  • getTasks - получение списка задач с возможностью фильтрации
Телефония
  • getCallStatistics - получение статистики звонков
Файлы
  • getFile - получение информации о файле по ID
Таймлайн
  • addTimelineComment - добавление комментария в таймлайн сущности
Сводная информация
  • getCrmSummary - получение сводной информации о CRM (количество лидов, сделок, контактов и т.д.)
Служебные инструменты
  • checkApiConnection - проверка соединения с API сервером

Настройка и использование

  1. Установите зависимости:
cd mcp-server
npm install

  1. Убедитесь, что REST API сервер Bitrix24 запущен на порту 3000 (или измените значение API_BASE_URL в файле mcp-server.js).

  2. Запустите MCP сервер:

node mcp-server.js
  1. Настройте языковую модель для использования MCP сервера, добавив его в конфигурацию MCP серверов.

Настройка Claude Desktop для работы с MCP сервером

Для использования Bitrix24 MCP сервера с Claude Desktop, необходимо создать или отредактировать файл конфигурации claude_desctop_config.json. Этот файл должен быть размещен в следующей директории:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Пример содержимого файла claude_desctop_config.json:

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/полный/путь/к/mcp-server/mcp-server.js"],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Где:

  • bitrix24 - уникальное имя MCP сервера, которое будет использоваться для обращения к нему
  • command - команда для запуска сервера (обычно node)
  • args - массив аргументов команды, включая полный путь к файлу mcp-server.js
  • env - объект с переменными окружения (можно оставить пустым, так как все настройки уже включены в mcp-server.js)
  • disabled - флаг, указывающий, отключен ли сервер (должен быть false для работы)
  • autoApprove - массив имен инструментов, которые могут быть вызваны без явного подтверждения пользователем (рекомендуется оставить пустым для безопасности)

После настройки файла конфигурации перезапустите Claude Desktop, и MCP сервер будет автоматически запущен и подключен к Claude. Теперь вы можете использовать инструменты Bitrix24 MCP сервера в диалоге с Claude.

Пример использования инструмента через языковую модель

// Пример вызова инструмента getLeads
const result = await model.useToolWithMcp("Bitrix24MCP", "getLeads", { filter: JSON.stringify({ STATUS_ID: "NEW" }) });
console.log(result); // Выводит список новых лидов

Обработка ошибок

Каждый инструмент включает обработку ошибок и возвращает структурированный ответ даже в случае возникновения проблем. Ошибки логируются в консоль для отладки.

Расширение функциональности

Для добавления новых инструментов используйте метод server.tool(), указав:

  1. Имя инструмента
  2. Схему параметров с использованием Zod
  3. Асинхронную функцию-обработчик, которая выполняет запрос и возвращает результат