AI导哈

CRM集成服务器

Kommo MCP Server是一个基于Fastify和Node.js的CRM集成服务器，支持多租户、JSON-RPC 2.0协议、智能缓存和输入验证，适用于企业CRM系统集成。

  • by cardosolucass96
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 cardosolucass96/kommo-mcp-server

使用说明

Kommo MCP服务器

MCP（模型上下文协议）服务器，通过Fastify + Node.js与KommoCRM集成。

🎯 特点

  • 多用户: 支持多个账户 Kommo 通过令牌 Bearer
  • 基于HTTP的MCP：Protocolo JSON-RPC 2.0（可流式传输）
  • 审批系统在多个注册表操作之前请求确认（通过采样）
  • 智能缓存：管道和营地定制缓存
  • 输入验证Zod 模式用于强大的参数验证
  • 类型安全带严格模式和完整字体的TypeScript
  • 错误处理使用 JSON-RPC 代码进行结构化错误处理
  • 日志记录与Fastify集成的日志系统
  • 安全代币验证，强制性环境变量

📦 安装

npm install
npm run build

⚙️ 配置

创建文件 .env 根 （copy of .env.example):

PORT=3000
HOST=0.0.0.0
MCP_PASSWORD=SuaSenhaSegura123

⚠️ 重要:

  • MCP_PASSWORD 是 义务 没有它服务器无法启动
  • 切勿在生产中使用弱密码或默认密码
  • 从不提交文件 .env 具有真实凭据

🚀 在本地运行

# Desenvolvimento (inicia servidor + MCP Inspector)
npm run dev

# Apenas o servidor
npm start

# Build + Servidor (sem inspector)
npm run build && npm start

# Watch mode (recompila automaticamente)
npm run dev:watch

# Apenas MCP Inspector
npm run inspector

快速启动：

# Instalar dependências
npm install

# Desenvolvimento (servidor + inspector)
npm run dev

# Produção
npm run build
npm start

🔐 认证

Formato do代币持有者：

MCP_PASSWORD|subdomain|kommoAccessToken

例如：

curl -H "Authorization: Bearer Admin123|mpcamotestecom|eyJ0eXAi..." \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:3000/mcp

📡 端点

方法 Endpoint 描述
得到 / 健康检查
得到 /health 健康检查
职位 /mcp MCP协议（JSON-RPC 2.0）
删除 /mcp 关闭会话
得到 /tools 工具列表（Legacy）
职位 /execute 遗产工具（Legacy Tool）

🔧 可用工具

工具 描述 验证
kommo_list_leads 列表/搜索线索✅ 这是一个计划。
kommo_update_lead 更新线索（名称，价格，状态，自定义字段） ✅ 这是一个计划。
kommo_add_notes 将笔记添加到 lead。✅ 这是一个计划。
kommo_add_tasks 创建任务/提醒✅ 这是一个计划。
kommo_list_pipelines 管道和阶段列表（缓存）
kommo_list_pipeline_stages 列出管道的阶段（缓存） ✅ 这是一个计划。
kommo_list_lead_custom_fields 列出自定义字段（缓存） -

缓存

  • 管道：10分钟
  • 实习：10分钟
  • 自定义字段时间： 1 小时

🔄 Uso com n8n

1. kommo_start_session  → Inicia atendimento com lead
2. kommo_update_lead    → Modifica dados
3. kommo_add_notes      → Registra observações
4. kommo_add_tasks      → Cria follow-ups
5. kommo_end_session    → Encerra atendimento

⚠️ 最佳实践与安全

安全

  • ✅ 通过环境变量强制使用密码
  • ✅ 使用 Zod schemas 验证输入
  • ✅ 多方验证令牌
  • ✅ 错误处理内容：
  • ✅ Fastify 错误日志

开发

  • ✅ TypeScript严格模式
  • ✅ Tipagens completas（禁食请求、禁食回复）
  • ✅ 集中在单独文件中的常量
  • ✅ 可重复使用的验证方案
  • ✅ TTL 可配置缓存

清洁代码

  • ✅ 责任分离（类型，模式，常量）
  • ✅ 错误代码padronizados（JSON-RPC 2.0）
  • ✅ 描述性错误消息
  • ✅ Early Return 验证

文档

  • 📄 README.md - 概述和设置
  • 📄 USAGE.md 使用curl的实际例子
  • 📄 APPROVAL-SYSTEM.md - 多个注册表交易的审批系统
  • 📄 src/constants.ts 常量和设置
  • 📄 src/schemas.ts 验证方案

🔐 审批系统

服务器通过 MCP采样 对于影响多个记录的操作。当您运行命令，如“添加注释到纸质插槽”，并有2个或更多的线索与此名称，代理 将寻求批准 在执行之前。

咨询 APPROVAL-SYSTEM.md 完整的细节。

🛠️ 开发

# Build
npm run build

# Dev mode
npm run dev

# Watch mode
npm run dev:watch

相关 MCP