Integrates with Kommo CRM to manage leads, including listing/searching leads, updating lead information (name, price, status, custom fields), adding notes, creating tasks/reminders, and managing pipelines and stages.
Kommo MCP Server
Servidor MCP (Model Context Protocol) para integração com o CRM Kommo via Fastify + Node.js.
🎯 Características
Multi-tenant: Suporta múltiplas contas Kommo via token Bearer
MCP over HTTP: Protocolo JSON-RPC 2.0 (Streamable)
Sistema de Aprovação: Pede confirmação antes de operações em múltiplos registros (via sampling)
Cache inteligente: Pipelines e campos customizados cacheados
Validação de entrada: Schemas Zod para validação robusta de parâmetros
Type-safe: TypeScript com strict mode e tipagens completas
Error handling: Tratamento de erros estruturado com códigos JSON-RPC
Logging: Sistema de logs integrado com Fastify
Segurança: Validação de tokens, variáveis de ambiente obrigatórias
📦 Instalação
⚙️ Configuração
Crie um arquivo .env na raiz (copie de .env.example):
⚠️ IMPORTANTE:
MCP_PASSWORDé OBRIGATÓRIO - o servidor não inicia sem eleNunca use senhas fracas ou padrão em produção
Nunca commite o arquivo
.envcom credenciais reais
🚀 Executar localmente
Quick start:
🔐 Autenticação
Formato do token Bearer:
Exemplo:
📡 Endpoints
Método | Endpoint | Descrição |
GET |
| Health check |
GET |
| Health check |
POST |
| MCP Protocol (JSON-RPC 2.0) |
DELETE |
| Encerrar sessão |
GET |
| Listar ferramentas (legacy) |
POST |
| Executar ferramenta (legacy) |
🔧 Ferramentas Disponíveis
Ferramenta | Descrição | Validação |
| Lista/busca leads | ✅ Zod schema |
| Atualiza lead (nome, preço, status, campos customizados) | ✅ Zod schema |
| Adiciona notas ao lead | ✅ Zod schema |
| Cria tarefas/lembretes | ✅ Zod schema |
| Lista pipelines e estágios (cached) | - |
| Lista estágios de um pipeline (cached) | ✅ Zod schema |
| Lista campos customizados (cached) | - |
Cache
Pipelines: 10 minutos
Estágios: 10 minutos
Campos customizados: 1 hora
🔄 Uso com n8n
⚠️ Boas Práticas e Segurança
Segurança
✅ Senha obrigatória via variável de ambiente
✅ Validação de entrada com Zod schemas
✅ Tokens multi-parte com validação
✅ Error handling estruturado
✅ Logs de erros com Fastify
Desenvolvimento
✅ TypeScript com strict mode
✅ Tipagens completas (FastifyRequest, FastifyReply)
✅ Constantes centralizadas em arquivo separado
✅ Schemas de validação reutilizáveis
✅ Cache configurável por TTL
Código Limpo
✅ Separação de responsabilidades (types, schemas, constants)
✅ Error codes padronizados (JSON-RPC 2.0)
✅ Mensagens de erro descritivas
✅ Validação early-return
Documentação
📄
README.md- Visão geral e setup📄
USAGE.md- Exemplos práticos de uso com curl📄
APPROVAL-SYSTEM.md- Sistema de aprovação para operações em múltiplos registros📄
src/constants.ts- Constantes e configurações📄
src/schemas.ts- Schemas de validação
🔐 Sistema de Aprovação
O servidor implementa um sistema de aprovação via MCP sampling para operações que afetam múltiplos registros. Quando você executa comandos como "adicione nota em lucas cardoso" e existem 2 ou mais leads com esse nome, o agente pedirá aprovação antes de executar.
Consulte