What is Bitrix24 Mcp Server

Bitrix24_MCP_Server is a server application that provides a REST API for interacting with Bitrix24 CRM. It uses the Model-Controller-Presenter (MCP) architectural pattern to organize code and ensure a clear separation of responsibilities among components.

Use cases

Use cases include automating data retrieval from Bitrix24 CRM, integrating Bitrix24 with other applications, managing tasks and contacts programmatically, and enhancing the functionality of existing Bitrix24 implementations.

How to use

To use Bitrix24_MCP_Server, clone the repository, install dependencies using npm, configure the environment variables in a .env file, and start the server using npm start.

Key features

Key features include full access to core Bitrix24 CRM entities (deals, leads, contacts, tasks, etc.), data formatting for client-side usage, request and response logging, error handling, and CORS support for frontend applications.

Where to use

Bitrix24_MCP_Server can be used in various fields that require customer relationship management, such as sales, marketing, project management, and customer support.

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

2. Установите зависимости:

npm install

3. Создайте файл .env в корневой директории проекта со следующими параметрами:

PORT=3000
BITRIX_DOMAIN=your-domain.bitrix24.ru
BITRIX_WEBHOOK_TOKEN=your-webhook-token
LOG_LEVEL=info

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

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: '[email protected]' }]
    };
    
    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

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

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

node mcp-server.js

4. Настройте языковую модель для использования 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. Асинхронную функцию-обработчик, которая выполняет запрос и возвращает результат