客徕徕 SCRM MCP Server

让 AI 助手通过标准 MCP 协议查询客户、理解会话、准备运营内容，并在确认后执行已有业务操作。

本项目将客徕徕 SCRM 的业务 API 封装为 42 个公开 MCP 工具，配套 17 个业务 Skills，提供 HTTP / stdio 接入、自动生成的工具手册、参数校验、写操作确认、预演和调用统计。

它是 AI 客户端与业务后端之间的接入服务，不是独立聊天机器人，也不包含业务数据库、模型服务或工作手机端。核心工具主要对接 wei-kefu-be 的接口契约；企业微信 wework-server 是相关项目，不能只替换 URL 就假定全部工具兼容。

微信（WeChat）：Linglanhuakaiyue（技术支持 / 合作）

联系我们 · 快速开始 · 客户端接入 · 工具清单 · 业务-skills · 关联仓库

MCP 在整个项目中的作用

传统工作台由人点击页面、查询数据和提交任务；MCP 把相同业务能力转换为 AI 客户端可发现、可调用的工具。Agent 可以先读业务数据，再组织分析和建议，经确认后调用后端完成操作。

flowchart LR
    Human[客服 / 运营人员] --> AI[支持 MCP 的 AI 客户端]
    AI <-->|HTTP 或 stdio| MCP[kelailai-mcp-server]
    MCP --> Tools[42 个工具 / 参数校验 / 确认与预演]
    AI --> Skills[17 个业务 Skills]
    Tools --> Backend[兼容业务 API 的后端]
    Backend --> DB[(业务数据库)]
    Backend <-->|任务与回执| Device[工作手机 / 设备端]
    Web[Web / 桌面工作台] <--> Backend

可以帮助完成的工作

• 客服准备：查好友和历史消息，整理客户画像、需求、跟进建议和公共话术。

• 会话处理：查私聊/群聊消息，定位会话，准备回复；获确认后调用消息发送工具。

• 朋友圈运营：准备与创建朋友圈任务、查看动态和评论、回复评论、查询好友动态并执行单条点赞操作。

• 群发与跟进：创建好友或群群发任务，查看明细与失败原因，按业务接口重试失败目标。

• 客户管理：查询分组、系统标签与微信原生标签，维护上下文记忆、号码组和自动加好友任务。

• 内容复用：上传文件、查询或收藏素材、维护公共话术及关键词回复。

• 运营分析：查询消息、好友、朋友圈和账号操作统计，结合 Skills 形成简报或复盘。

• 知识辅助：检索企业知识库，辅助形成有业务依据的回复。

分析与文案由接入的模型完成，数据查询和执行结果由后端提供。模型质量、账号权限、设备状态和接口版本共同影响实际效果。

Related MCP server: Corebee MCP Server

项目优势

工具清单过滤只影响 tools/list，不是权限隔离，不会禁止调用清单之外的工具。权限、授权和执行结果必须以服务端校验为准。

快速开始

1. 安装与构建

需要 Node.js 22.14+，推荐 Node.js 24 LTS。

git clone https://github.com/lwang998/kelailai-mcp-server.git
cd kelailai-mcp-server
npm ci --ignore-scripts --no-audit --no-fund
npm run build

核心 HTTP / stdio 服务不需要 Electron 或 SQLite 原生模块，因此使用 --ignore-scripts 安装即可进行服务构建与单元测试。src/electron/ 保留历史桌面集成代码，本次不将其视为完成验收的桌面产品。

2. 配置自己的环境

cp .env.example .env
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

PowerShell 可用 Copy-Item .env.example .env。将生成的随机值填入 .env 的 MCP_API_TOKEN，再按自己的环境修改后端地址。不要提交 .env。

KEFU_BASE_URL=http://127.0.0.1:13086
UPLOAD_URL=http://127.0.0.1:18081/fileUpload
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=3010
MCP_PUBLIC_BASE_URL=http://127.0.0.1:3010
MCP_API_TOKEN=填入自己生成的随机值
MCP_AUTH_DISABLED=false
MCP_BUSINESS_AUTH_DISABLED=false
MCP_STATS_ENABLED=false

.env 通过 dotenv 从启动工作目录读取。没有 MCP_API_TOKEN 且未显式关闭访问鉴权时，HTTP 服务拒绝启动；公开示例默认只监听本机。

3. 启动与查看手册

npm start

• 健康检查：http://127.0.0.1:3010/health

• 接入页面：http://127.0.0.1:3010/onboard

• 精简接入信息：http://127.0.0.1:3010/onboard.json

• 完整工具文档：http://127.0.0.1:3010/onboard.json?full=1

• MCP 协议地址：http://127.0.0.1:3010/mcp

健康检查和接入手册可以在没有真实后端的情况下打开。业务工具需要自己的兼容后端与业务凭据；HTTP 200 的接入页面并不表示已完成业务认证。

客户端接入

HTTP：服务密钥与业务凭据分开

服务访问使用 x-mcp-token，业务凭据使用 token，避免占用同一个 Authorization 头。

{
  "mcpServers": {
    "kelailai": {
      "url": "http://127.0.0.1:3010/mcp?tools=core&schema=slim",
      "headers": {
        "x-mcp-token": "YOUR_MCP_API_TOKEN",
        "token": "YOUR_BUSINESS_TOKEN"
      }
    }
  }
}

这是通用配置形状，具体字段和环境变量引用语法以客户端为准。已有业务 API Key / JWT 时填入自己的凭据；没有业务 token 时，可以先仅配置服务密钥，调用 auth_login，再把返回的 token 配到业务头中。

initialize、tools/list、ping 和登录引导工具不要求已存在的业务 JWT，但仍受启用的 HTTP 服务访问鉴权控制。其他业务调用默认校验业务凭据。公开接入手册只输出密钥占位引用，不回传服务端实际密钥。

stdio：由客户端启动本地进程

{
  "mcpServers": {
    "kelailai": {
      "command": "node",
      "args": ["/absolute/path/kelailai-mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "KEFU_BASE_URL": "http://127.0.0.1:13086",
        "KEFU_TOKEN": "YOUR_BUSINESS_TOKEN",
        "UPLOAD_URL": "http://127.0.0.1:18081/fileUpload",
        "MCP_STATS_ENABLED": "false"
      }
    }
  }
}

替换为自己的绝对路径。stdio 不使用 HTTP 层的服务密钥，应由启动它的客户端隔离进程与凭据；工具请求仍需要被后端接受。stdio 保持统计关闭，以免历史统计的标准输出污染 MCP 通信。

更详细的 HTTP 调用和鉴权说明见 docs/USAGE.md。

工具清单

写操作需在用户明确确认后传入 confirm=true；dry_run=true 用于预演工具将构造的后端调用，不代表业务已经执行。预演不会调用真实 BackendClient，但 URL 文件上传的准备过程可能抓取 source_url，无网络预演应使用 base64 文件输入。

可用工具（42 个，与注册表一致）

完整 action、参数、返回字段以自身服务的 /onboard.json?full=1 和 tools/list 为准。旧工具名通过 aliases 保留兼容，但不计入公开工具数量。

业务 Skills

Skills 是随仓提供的 Markdown 工作流说明，由 Agent 阅读和执行；它们不等同于后台自动开启的定时任务。

源码在 skills/。服务支持 /skills/<id>.md 及对应 references 路径，默认需要业务鉴权。不要将 Skills 中的示例域名当成可用服务地址。

实时消息盒子

普通工具查询和发送不要求安装盒子。持续收消息与后台自动回复需要额外部署 scrm-auto-reply 对应的本机组件、兼容后端推送协议和模型/Agent 驱动。

• 当前工作流使用本机 39202 端口的消息盒子，提供 wait / peek / ack 等 HTTP 接口。

• 盒子与驱动源码保存在该 Skill 的 references Markdown 中；scripts/build-box-exe.mjs 可用 Bun 构建分发程序。

• 仓库不附可执行程序。/dl/* 在没有自行构建并配置产物时会返回 404。

• 历史 Bridge 39200 不是当前接入主路径；远程 MCP 不提供收件箱工具。

• 可选 /box-ws 中继默认关闭。不要把公开 MCP 服务启动成功理解为实时盒子已经部署。

配置、权限与边界

工具曝光策略定义于 EXPOSURE_POLICY：账号权限、密钥计费、内部运维、发布与设备授权等接口不直接作为业务工具开放。工具写入还会调用后端的设备资格检查，并按后端权限与业务规则执行。

这不是“AI 无限制接管系统”。实际操作应先查询目标、展示拟执行内容并获用户确认，之后调用工具、检查返回码和任务回执；接口受理不等于手机已执行成功。

测试与开发

npm run build
npm test
npm run check:confirm

测试覆盖工具注册表、Schema、合并工具族、确认与预演、错误分类、鉴权、token 续期、日志脱敏、HTTP 接入、Skills 和 README 一致性。材料类型测试使用仓库内协议枚举快照，无需私有兄弟仓库。

公开版本修复了接入页回显服务密钥的问题，并增加回归测试；入口会加载 .env，生成的默认接入指令区分服务密钥和业务凭据。构建会复制统计页到 dist，避免源码有页面而构建产物缺失。

当前验证基线：335 个测试通过，53 个写入口的确认门禁与预演检查通过；真实 MCP SDK 的 HTTP / stdio 握手、42 个工具发现和本地引导调用通过。测试与协议握手通过不等于已完成真实账号、设备发送、第三方模型或跨平台盒子的联调验收。

关联仓库

各仓库状态以实际发布内容为准。文件服务、设备端、授权/资格数据和模型能力需要根据部署场景另行配置。

在线体验与联系方式

整体产品测试站：https://test.kelailai.chat/

这是维护者授权公开的网页体验账号，不是本仓库初始化账号，也不保证具备 MCP 写入权限。请使用模拟数据；测试环境功能以账号权限和设备状态为准。公开版不自动连接测试站。

• 微信（WeChat）：Linglanhuakaiyue（技术支持 / 合作）

• 联系页面：https://kelailai.chat/contact-us.html

• 问题与建议：GitHub Issues

• 可交流：MCP 接入、私有化部署、Agent 工作流、业务系统集成与二次开发。

许可证

项目自有代码采用 MIT License。npm 依赖保留其各自许可证，参见 THIRD_PARTY_NOTICES.md。公开仓库不包含生产配置、真实业务数据、私钥、登录态、运行日志或已构建的客户端程序。