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

Related MCP server: Kommo MCP Server

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.

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

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

Licença

Distribuído sob a licença MIT.