Kommo MCP Server

English documentation

Servidor MCP (Model Context Protocol) para integração com o Kommo CRM. Expõe tools, resources e prompts para clientes MCP (Cursor, Claude Desktop, etc.).

Sumário

• Funcionalidades
• Pré-requisitos
• Início rápido
• Configuração
• Execução
• Integração com clientes MCP
• Endpoints
• Ferramentas MCP
• Resources
• Prompts
• Estrutura do projeto
• Exemplos de uso
• Troubleshooting
• Documentação
• Compatibilidade e suporte
• Contribuindo
• Segurança
• Licença

Funcionalidades

• MCP moderno e compatível: revisão 2026-07-28 pelo SDK oficial, com compatibilidade stateless para clientes da família 2025
• Dois transportes oficiais: Streamable HTTP para serviços remotos e stdio para clientes locais
• 23 tools: leads, contatos, empresas, tarefas, pipelines, notas, relatórios, dashboard, Salesbot, motivos de perda
• 5 resources: relatório de vendas, pipelines, motivos de perda, dashboard, conta
• 4 prompts: templates para análise de vendas, leads, pipelines e motivos de perda
• ask_kommo: interface conversacional em linguagem natural
• Arquitetura modular: código organizado em módulos (kommo-api, mcp/, ask-kommo)
• Segurança: validação de Origin, validação dos argumentos das tools e autenticação obrigatória fora de localhost

Pré-requisitos

• Node.js 22.13+
• Docker (opcional)
• Token de acesso do Kommo (integração privada ou OAuth2) — ver documentação do Kommo

Início rápido

git clone https://github.com/Miguelgbastos/Kommo-MCP.git
cd Kommo-MCP
npm install
cp env.example .env
# edite .env com KOMMO_BASE_URL e KOMMO_ACCESS_TOKEN
npm run build
npm start

O servidor sobe em http://127.0.0.1:3001/mcp.

Configuração

1. Copie o arquivo de exemplo:

   cp env.example .env
   

2. Configure no .env:

   KOMMO_BASE_URL=https://seu-dominio.kommo.com
   KOMMO_ACCESS_TOKEN=seu-token-aqui
   

Variáveis de ambiente

Execução

Desenvolvimento:

npm install
npm run dev        # ts-node
# ou
npm run build && npm start

Cliente local via stdio:

npm run build
npm run start:stdio

Docker:

docker build -t kommo-mcp-server .
docker run -d -p 3001:3001 \
  -e KOMMO_BASE_URL=https://seu-dominio.kommo.com \
  -e KOMMO_ACCESS_TOKEN=seu-token \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_AUTH_TOKEN=gere-um-segredo-longo \
  --name kommo-mcp-server kommo-mcp-server

Em produção, coloque o servidor atrás de um reverse proxy com TLS e defina MCP_AUTH_TOKEN + MCP_ALLOWED_ORIGINS. O servidor se recusa a iniciar em um endereço não local sem MCP_AUTH_TOKEN, inclusive quando createApp() é usado diretamente. A imagem Docker usa 127.0.0.1 por padrão; para publicar a porta, configure conscientemente MCP_HOST=0.0.0.0 junto com um token longo.

A confirmação explícita é obrigatória por padrão nas tools de escrita. Use MCP_CONFIRM_WRITES=false somente em automações controladas que assumam esse risco; o servidor registra um aviso operacional quando essa proteção é desativada. As tools de escrita anunciam destructiveHint; as consultas anunciam readOnlyHint pelo protocolo MCP.

Integração com clientes MCP

Cursor

O pacote npm ainda não foi publicado. Até a release v3, compile o projeto e adicione ao ~/.cursor/mcp.json o caminho absoluto do arquivo gerado:

{
  "mcpServers": {
    "kommo": {
      "command": "node",
      "args": ["/caminho/absoluto/Kommo-MCP/dist/stdio.js"],
      "env": {
        "KOMMO_BASE_URL": "https://seu-dominio.kommo.com",
        "KOMMO_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Para o servidor HTTP:

Adicione ao arquivo ~/.cursor/mcp.json (ou nas configurações do projeto em .cursor/mcp.json):

{
  "mcpServers": {
    "kommo": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

Claude Desktop

Para uma implantação remota com HTTPS, abra Settings → Connectors → Add connector e informe a URL pública do endpoint, por exemplo https://mcp.seudominio.com/mcp.

Para execução local, use a mesma configuração command/args/env acima no claude_desktop_config.json. Servidores HTTP remotos devem ser adicionados pela tela de Connectors.

Endpoints

• MCP: POST http://localhost:3001/mcp — negociação moderna via server/discover
• Health: GET http://localhost:3001/health
• Readiness: GET http://localhost:3001/ready — verifica se URL e token obrigatórios foram configurados

Ferramentas MCP

Conta e dashboard

Leads

Pipelines e relatórios

Contatos, empresas e tarefas

Notas

Motivos de perda e Salesbot

IA conversacional

Resources

Prompts

Estrutura do projeto

src/
├── kommo-api.ts             # Cliente da API Kommo
├── ask-kommo.ts             # Lógica conversacional ask_kommo
├── http-streamable.ts       # Servidor MCP HTTP
├── stdio.ts                 # Servidor MCP local por stdin/stdout
└── mcp/
    ├── server.ts            # Definição oficial do servidor MCP
    ├── types.ts             # Tipos MCP
    ├── tool-definitions.ts  # Schemas das tools
    ├── tool-handlers.ts     # Execução das tools
    ├── resources.ts         # Resources MCP
    └── prompts.ts           # Prompts MCP

Exemplos de uso

Clientes compatíveis negociam a revisão automaticamente por server/discover. Ao usar o cliente TypeScript oficial, fixe a revisão para evitar fallback silencioso para servidores antigos:

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const client = new Client(
  { name: 'minha-integracao', version: '1.0.0' },
  { versionNegotiation: { mode: { pin: '2026-07-28' } } },
);

const transport = new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3001/mcp'));

await client.connect(transport);
const { tools } = await client.listTools();

Clientes da família 2025 são atendidos automaticamente pelo modo stateless. Clientes modernos podem fixar 2026-07-28 conforme o exemplo acima.

Troubleshooting

• 401 Unauthorized da API do Kommo — verifique se KOMMO_ACCESS_TOKEN está válido e se KOMMO_BASE_URL aponta para o subdomínio correto da sua conta.
• Cliente MCP não conecta — confirme se MCP_HOST permite conexões do cliente (0.0.0.0 para acesso remoto) e se MCP_ALLOWED_ORIGINS inclui a origem do cliente, quando definido.
• 403 no /mcp — se MCP_AUTH_TOKEN estiver definido, é preciso enviar Authorization: Bearer ou X-API-Key: .
• 503 no /ready — configure KOMMO_BASE_URL com HTTPS e defina KOMMO_ACCESS_TOKEN antes de iniciar o serviço real.
• 429 do Kommo — todas as chamadas compartilham um limitador coordenado; leituras usam backoff e Retry-After, enquanto escritas não são repetidas automaticamente para evitar duplicidade.
• 429 do /mcp — o servidor limita cada endereço cliente a 120 requisições por minuto por processo; ajuste MCP_RATE_LIMIT_PER_MINUTE se necessário. O endereço do proxy é usado por padrão, pois trust proxy não é habilitado automaticamente.
• Docker HEALTHCHECK falha — a imagem usa node --eval para o healthcheck, verifique se a porta interna corresponde a PORT.
• Erros de build TypeScript — rode npm run typecheck para ver mensagens detalhadas. Requer Node.js 22.13+.

Documentação

• docs/MCP_EVOLUCAO.md — plano de evolução e conformidade MCP
• docs/KOMMO_API_EVOLUCAO.md — evoluções da API Kommo
• Kommo para desenvolvedores
• Changelog Kommo
• CHANGELOG.md deste projeto
• ROADMAP.md — prioridades e oportunidades de contribuição
• MAINTAINERS.md — manutenção, revisão e releases
• docs/COMPATIBILITY.md — matriz automatizada e checklist de validação manual em clientes MCP

Compatibilidade e suporte

Suporte comunitário ocorre por Issues e Discussions, sem garantia de tempo de resposta. Veja as responsabilidades em MAINTAINERS.md.

Contribuindo

Contribuições são muito bem-vindas! Leia o CONTRIBUTING.md para o fluxo completo e o Código de Conduta para as regras da comunidade.

Sugestões rápidas:

• Abra uma issue usando os templates.
• Envie um PR pequeno e focado, com descrição do que muda e por quê.
• Rode npm run typecheck, npm run lint, npm test, npm run format:check e npm run audit:prod antes de enviar.

Segurança

Para reportar vulnerabilidades, envie um e-mail para [email protected]. O processo está em SECURITY.md. Não abra issues públicas para problemas de segurança.

Licença

Distribuído sob a licença MIT.