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