Kommo MCP服务器
MCP(模型上下文协议)服务器,通过Fastify + Node.js与KommoCRM集成。
🎯 特点
- 多用户: 支持多个账户 Kommo 通过令牌 Bearer
- 基于HTTP的MCP:Protocolo JSON-RPC 2.0(可流式传输)
- 审批系统在多个注册表操作之前请求确认(通过采样)
- 智能缓存:管道和营地定制缓存
- 输入验证Zod 模式用于强大的参数验证
- 类型安全带严格模式和完整字体的TypeScript
- 错误处理使用 JSON-RPC 代码进行结构化错误处理
- 日志记录与Fastify集成的日志系统
- 安全代币验证,强制性环境变量
📦 安装```bash
npm install
npm run build
## ⚙️ 配置
创建文件 `.env` 根 (copy of `.env.example`):```env
PORT=3000
HOST=0.0.0.0
MCP_PASSWORD=SuaSenhaSegura123
⚠️ 重要:
MCP_PASSWORD是 义务 没有它服务器无法启动- 切勿在生产中使用弱密码或默认密码
- 从不提交文件
.env具有真实凭据
🚀 在本地运行```bash
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
快速启动:```bash
# Instalar dependências
npm install
# Desenvolvimento (servidor + inspector)
npm run dev
# Produção
npm run build
npm start
🔐 认证
Formato do代币持有者:```
MCP_PASSWORD|subdomain|kommoAccessToken
例如:```bash
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```
- kommo_start_session → Inicia atendimento com lead
- kommo_update_lead → Modifica dados
- kommo_add_notes → Registra observações
- kommo_add_tasks → Cria follow-ups
- 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` 完整的细节。**
## 🛠️ 开发```bash
# Build
npm run build
# Dev mode
npm run dev
# Watch mode
npm run dev:watch
