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 20+
• 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.

Ative MCP_CONFIRM_WRITES=true quando o cliente permitir confirmação
explícita. As tools de escrita anunciam destructiveHint; as consultas
anunciam readOnlyHint pelo protocolo MCP.

Integração com clientes MCP

Cursor

Para execução local por stdio, adicione ao ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kommo": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "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 <token> ou X-API-Key: <token>.
• 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.
• 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 20+.

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, veja SECURITY.md. Não
abra issues públicas para problemas de segurança.

Licença

Distribuído sob a licença MIT.