Bitrix24_MCP_服务器

Name: Bitrix24_MCP_服务器
Author: OneAtDrt

作者：OneAtDrt10 星标更新：2025-03-28

安装使用来源：spider==github.com

项目介绍

Bitrix24 MCP Server

概述

Bitrix24 MCP (Model-Controller-Presenter) Server 是一个服务器应用程序，提供与 Bitrix24 CRM 交互的 REST API。该服务器采用 MCP 架构模式来组织代码，并确保组件之间有明确的责任划分。

特性

完整访问 Bitrix24 CRM 的主要实体（交易、潜在客户、联系人、任务等）
数据格式化以便于客户端使用
请求和响应的日志记录
错误和异常处理
支持 CORS 以与前端应用进行交互

要求

Node.js（版本 14.x 或更高）
npm（版本 6.x 或更高）
具有已配置 webhook 的 Bitrix24 访问权限

安装

克隆仓库：

git clone https://github.com/your-username/bitrix24-mcp-server.git
cd bitrix24-mcp-server

安装依赖：

npm install

在项目根目录创建 .env 文件，包含以下参数：

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

启动服务器：

npm start

架构

服务器基于 MCP（Model-Controller-Presenter）架构模式构建：

Model (Bitrix24Model)：负责与 Bitrix24 API 进行交互并处理数据。
Controller (Bitrix24Controller)：处理 HTTP 请求，应用业务逻辑，并协调模型和展示器的工作。
Presenter (Bitrix24Presenter)：格式化数据以便于客户端展示。

API 端点

任务

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

联系人

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

交易

GET /api/deals - 获取交易列表
- 查询参数：
  - 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 - 获取潜在客户列表
- 查询参数：
  - filter - JSON 格式的过滤字符串（可选）
GET /api/leads/:id - 根据 ID 获取潜在客户
POST /api/leads - 创建新的潜在客户
- Body: 包含潜在客户数据的对象
PUT /api/leads/:id - 更新潜在客户
- Body: 包含更新数据的对象
GET /api/lead-statuses - 获取潜在客户状态

活动（事务）

GET /api/activities - 获取活动列表
- 查询参数：
  - filter - JSON 格式的过滤字符串（可选）
GET /api/activities/:id - 根据 ID 获取活动
POST /api/activities - 创建新的活动
- Body: 包含活动数据的对象
PUT /api/activities/:id - 更新活动
Body: 包含更新数据的对象

用户

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

时间线

POST /api/timeline-comment/:entityType/:entityId - 添加时间线评论
- Body: { "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);
  }
}

创建新的潜在客户

// 客户端代码
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: 'zhangsan@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 是一个为 Bitrix24 实现的 MCP（Model Context Protocol）服务器，它提供了一组工具，用于通过 REST API 服务器与 Bitrix24 API 进行交互。MCP 服务器作为语言模型（LLM）和 Bitrix24 REST API 服务器之间的中间层，允许语言模型通过结构化的工具执行 Bitrix24 数据操作。

工作原理

MCP 服务器使用 @modelcontextprotocol/sdk 库来创建和注册可以由语言模型调用的工具。每个工具都是一个函数，它：

接受由 Zod 方案定义的参数
执行到 Bitrix24 REST API 服务器的请求
返回结构化的结果

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 服务器的连接

配置和使用

安装依赖：

cd mcp-server
npm install

确保 Bitrix24 REST API 服务器正在端口 3000 上运行（或更改 mcp-server.js 文件中的 API_BASE_URL 值）。
启动 MCP 服务器：

node mcp-server.js

配置语言模型以使用 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。现在您可以在与 Claude 的对话中使用 Bitrix24 MCP 服务器的工具了。

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

// 示例调用 getLeads 工具
const result = await model.useToolWithMcp("Bitrix24MCP", "getLeads", { filter: JSON.stringify({ STATUS_ID: "NEW" }) });
console.log(result); // 输出新潜在客户列表

错误处理

每个工具都包含错误处理，并在出现问题时返回结构化的响应。错误会被记录到控制台以供调试。

功能扩展

要添加新的工具，使用 server.tool() 方法，指定：

工具名称
使用 Zod 定义的参数方案
异步处理函数，执行请求并返回结果