AI导哈

CRM REST API服务器

Bitrix24 MCP Server是一个基于MCP架构的REST API服务器，提供与Bitrix24 CRM交互的功能，包括管理交易、线索、联系人、任务等核心CRM实体。

  • by OneAtDrt
  • JavaScript
  • 本地部署
  • 13 星标
  • 更新于
在 GitHub 查看 OneAtDrt/Bitrix24_MCP_Server

使用说明

Bitrix24 MCP服务器

概述

Bitrix24 MCP（Model Controller Presenter）服务器是一个服务器应用程序，提供REST API与Bitrix24 CRM交互。服务器使用MCP体系结构模式组织代码并确保组件之间明确的责任划分。

特点

  • 完全访问Bitrix24 CRM的基本实体（交易、线索、联系人、任务等）
  • 格式化数据以方便客户使用
  • 查询和响应日志
  • 处理错误和例外
  • CORS支持与前端应用程序交互

要求

  • Node.js（14.x或更高版本）
  • NPM（6.x或更高版本）
  • 使用自定义WebHook访问Bitrix24

安装

  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）架构模式构建：

  • 型号（Bitrix24型号）：负责与Bitrix24 API的交互和数据处理。
  • 控制器（Bitrix24控制器）：处理HTTP请求，应用业务逻辑并协调模型和提交程序的工作。
  • 演示者（Bitrix24演示者）：格式化数据以呈现给客户。

API终点

任务

  • GET /api/tasks -获取任务列表
    • 查询参数：
      • filter -带过滤器的JSON字符串（可选）

联系方式

  • GET /api/contacts -获取联系人列表
    • 查询参数：
      • filter -带过滤器的JSON字符串（可选）

交易

  • GET /api/deals -获取交易列表
    • 查询参数：
      • filter -带过滤器的JSON字符串（可选）
  • GET /api/deals/:id -"олучениесделкипоID
  • POST /api/deals 创建新交易
    • 实体：交易对象
  • PUT /api/deals/:id - Обновление сделки
    • Body:要更新的数据对象
  • GET /api/deal-categories -获取销售漏斗
  • GET /api/deal-stages/:categoryId? -获取指定漏斗的交易阶段

利达

  • GET /api/leads -获取Lids列表
    • 查询参数：
      • filter -带过滤器的JSON字符串（可选）
  • GET /api/leads/:id -"олучениелидапоID
  • POST /api/leads 创建新的Lida
    • 身体：李德数据对象
  • PUT /api/leads/:id - LED更新
    • Body:要更新的数据对象
  • GET /api/lead-statuses -获得Lid状态

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

  • GET /api/activities -获取活动列表
    • 查询参数：
      • filter -带过滤器的JSON字符串（可选）
  • GET /api/activities/:id -"олучениеактивностandпоID
  • POST /api/activities 建立新的活动
    • 身体：活动数据对象
  • PUT /api/activities/:id - 活动更新
    • Body:要更新的数据对象

用户

  • GET /api/users -获取用户列表
    • 查询参数：
      • filter -带过滤器的JSON字符串（可选）
  • GET /api/users/:id 获取用户ID

时间线

  • POST /api/timeline-comment/:entityType/:entityId -在定时线上添加评论
    • 主体： { "comment": "Текст комментария" }

电话

  • GET /api/call-statistics -获取通话统计数据
    • 查询参数：
      • 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);
  }
}

创建新的Lida

// Клиентский код
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令牌以最小化风险

许可证

麻省理工学院

MCPСервер（MCP服务器.js）

概述

mcp-server.js 它是Bitrix24服务器的MCP（Model Context Protocol）实现，它提供了一组工具，用于通过REST API服务器与Bitrix24 API通信。MCP服务器充当语言模型（LLM）和Bitrix24 REST API服务器之间的中间层，允许语言模型通过结构化工具对Bitrix24数据进行操作。

工作原理

MCP 服务器使用库 @modelcontextprotocol/sdk 创建和注册可以由语言模型调用的工具。每个工具都有一个功能：

  1. 接受使用ZOD原理图定义的参数
  2. 向Bitrix24服务器执行REST API请求
  3. 以结构化格式返回结果

MCP服务器通过STDIO传输运行，允许它通过标准I/O线程与语言模型通信。

可用工具

MCP服务器提供以下工具组：

利达

  • getLeads -获取带有过滤选项的潜在客户列表
  • getLead -通过ID获取有关特定利达的信息
  • createLead 创建新的Lida
  • updateLead 更新现有Lida
  • getLeadStatuses -获取Lid状态列表

交易

  • getDeals -获取具有过滤功能的交易列表
  • getDeal -通过ID获取特定交易的信息
  • createDeal 创建新交易
  • updateDeal 更新现有交易
  • getDealCategories -获取销售漏斗列表
  • getDealStages -获取指定漏斗的交易阶段列表

联系方式

  • getContacts -获取具有过滤功能的联系人列表
  • getContact -通过ID获取特定联系人的信息

活动

  • getActivities -获取具有过滤功能的活动列表
  • getActivity -通过ID获取特定活动的信息
  • createActivity -创建新活动
  • updateActivity 更新现有活动

用户

  • getUsers -获取具有过滤功能的用户列表
  • getUser -通过ID获取特定用户的信息

任务

  • getTasks -获取具有筛选功能的任务列表

电话

  • getCallStatistics -获取通话统计数据

文件

  • getFile -通过ID获取文件信息

时间线

  • addTimelineComment -向实体的定时线添加注释

A.总表

  • getCrmSummary -获取CRM摘要信息（线索、交易、联系人等数量）

工具

  • checkApiConnection -验证与API服务器的连接

设置和使用

  1. 建立依赖关系：
cd mcp-server
npm install

  1. 验证Bitrix24 REST API服务器是否在端口3000上运行（或更改值） API_BASE_URL 在文件中 mcp-server.js).

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

node mcp-server.js
  1. 通过将语言模型添加到MCP服务器配置中来配置使用MCP服务器的语言模型。

为MCP服务器配置Claude Desktop

要在Claude桌面上使用Bitrix24 MCP服务器，必须创建或编辑配置文件 claude_desctop_config.json此文件应位于以下目录中：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %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。您现在可以在Claude对话框中使用Bitrix24 MCP服务器工具。

通过语言模型使用工具的示例

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

错误处理

每个工具都包括错误处理，并返回结构化的响应，即使出现问题。错误记录到控制台进行调试。

增强功能

要添加新工具，请使用方法 server.tool()其中指出：

  1. 工具名称
  2. 使用ZOD的参数图
  3. 执行查询并返回结果的异步处理程序函数

相关 MCP