kommo-mcp

Servidor MCP (Model Context Protocol) self-hosted para a Kommo CRM (antiga amoCRM, API v4).

Conecta o Claude — ou qualquer cliente MCP (Claude Code, Claude Desktop, Cursor, etc.) — direto na sua conta Kommo, usando um token de longa duração seu. Sem intermediários: as credenciais e os dados trafegam apenas entre a sua máquina/servidor e a API da Kommo.

Com ele, o assistente passa a agir no CRM em tempo real (criar/mover leads, escrever tarefas, trocar responsáveis, auditar o que os bots fizeram) em vez de depender só de dashboards e planilhas.

Sumário

• Recursos

• Pré-requisitos

• Instalação

• 1. Gerar o token da Kommo

• 2. Configurar o .env

• 3. Testar a conexão

• Usar no Claude Code

• Usar em outros clientes MCP

• Referência das tools

• Estrutura do projeto

• Segurança

• Limitações conhecidas

• Troubleshooting

• Deploy em servidor (VPS)

• Licença

Related MCP server: PipeDrive MCP Server

Recursos

41 tools, 4 prompts e 8 resources MCP:

Formato de resposta: listagens devolvem { items, page, has_more } com itens resumidos e legíveis (funil/etapa/responsável por nome, telefone do contato principal, datas no fuso da conta); raw: true devolve o payload cru da API. Todas as tools declaram MCP annotations (readOnlyHint/destructiveHint), então clientes conseguem liberar leituras e travar escritas por protocolo.

Prompts (viram comandos no cliente MCP): auditoria-do-dia, fila-agora, leads-parados, relatorio-perdas. Resources: kommo://account, kommo://pipelines, kommo://users, kommo://custom-fields/{leads,contacts,companies}, kommo://loss-reasons, kommo://task-types.

Pré-requisitos

• Node.js ≥ 18 (usa fetch nativo; sem dependências de runtime além do SDK do MCP).

• Uma conta Kommo com permissão de administrador (necessária para gerar o token).

• Um cliente MCP — este README foca no Claude Code.

Instalação

git clone https://github.com/RonaldoESantosRevOps/kommo-mcp.git
cd kommo-mcp
npm install

1. Gerar o token da Kommo

Use um token de longa duração (não expira por anos e não precisa de refresh):

1. Na Kommo, vá em Configurações → Integrações.

2. Clique para criar uma integração privada (não precisa preencher Redirect URL nem webhook).

3. Abra a aba Chaves e escopos.

4. Clique em Gerar token de longa duração, escolha a validade (até 5 anos) e copie o token.

5. O escopo crm já é suficiente para todas as tools.

Guarde o token com cuidado — ele dá acesso total ao seu CRM com os seus direitos de admin.

Documentação oficial: https://pt-developers.kommo.com/docs/token-de-longa-duração

2. Configurar o .env

Copie o exemplo e preencha:

cp .env.example .env

KOMMO_SUBDOMAIN=seusubdominio        # a parte antes de .kommo.com (ex.: "minhaempresa")
KOMMO_TOKEN=seu_token_de_longa_duracao

O .env já está no .gitignore — nunca o versione. O servidor lê esse arquivo automaticamente (ele fica ao lado do index.mjs), então você não precisa exportar variáveis de ambiente manualmente.

3. Testar a conexão

npm run smoke

Esse smoke test sobe o servidor via protocolo MCP e chama tools de leitura contra a API real. Saída esperada (resumida):

✓ tools expostas: 41
✓ annotations ok (16 tools read-only)
✓ allowlist bloqueia host externo no passthrough
✓ kommo_account -> <Nome da sua conta> (id ..., BRL)
✓ kommo_pipelines -> N funis; principal: ...
✓ kommo_users -> N usuários (M inativos: ...)
✓ kommo_search_leads -> resumo ok; ...
✓ kommo_get_events -> 5 eventos traduzidos (autor, etapas por nome, ISO)
✓ kommo_talks / kommo_unsorted / kommo_tags / kommo_loss_reasons ...
✓ SMOKE OK

O teste de escrita opcional (node smoke.mjs --write) faz um round-trip inofensivo de webhook (assina, confere e remove), sem tocar em leads ou contatos.

Se aparecer HTTP 401 Invalid user name or password, veja Troubleshooting.

Usar no Claude Code

Registrar o servidor

claude mcp add kommo -s user -- node /caminho/absoluto/para/kommo-mcp/index.mjs

• Use o caminho absoluto até o index.mjs (ex.: ~/kommo-mcp/index.mjs resolvido para algo como /home/voce/kommo-mcp/index.mjs).

• O servidor lê o .env dele mesmo, então não é preciso passar variáveis no comando.

Escopos (-s):

Verificar

claude mcp get kommo     # deve mostrar "Status: ✔ Connected"
claude mcp list          # lista todos os servidores MCP

Reinicie o Claude Code depois de registrar: as tools de um servidor MCP só entram quando a sessão inicia.

Permissões: leitura sem prompt, escrita sempre confirmando

Por padrão o Claude Code pede confirmação a cada chamada de tool. Você pode liberar apenas as tools de leitura (consultas) e manter as de escrita sempre pedindo OK. No seu ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__kommo__kommo_account",
      "mcp__kommo__kommo_pipelines",
      "mcp__kommo__kommo_users",
      "mcp__kommo__kommo_custom_fields",
      "mcp__kommo__kommo_search_leads",
      "mcp__kommo__kommo_get_lead",
      "mcp__kommo__kommo_list_tasks",
      "mcp__kommo__kommo_search_contacts",
      "mcp__kommo__kommo_search_companies",
      "mcp__kommo__kommo_list_webhooks",
      "mcp__kommo__kommo_get_events",
      "mcp__kommo__kommo_tags",
      "mcp__kommo__kommo_loss_reasons",
      "mcp__kommo__kommo_talks",
      "mcp__kommo__kommo_unsorted",
      "mcp__kommo__kommo_catalog_elements"
    ]
  }
}

Todas as tools de escrita (criar/editar leads, contatos, empresas, tarefas, notas, etapas, campos custom, vínculos, webhooks, lotes, Inbox accept/decline, Salesbot e upload) e o passthrough kommo_request continuam pedindo confirmação — o comportamento seguro recomendado. As 16 tools de leitura também declaram readOnlyHint: true via MCP annotations, então clientes que respeitam annotations já as tratam como seguras.

Exemplos de uso (linguagem natural)

Depois de registrado, é só pedir ao Claude:

• "Liste os leads parados na etapa 'Interesse em Agendar' do funil principal."

• "O que os bots fizeram hoje? Puxe os eventos com created_by=0 das últimas 6 horas."

• "Crie um lead 'João da Silva', telefone +55 11 99999-9999, no funil de qualificação."

• "Mova o lead #12345 para 'Pagamento' e troque o responsável para a Ana."

• "Crie uma tarefa de follow-up amanhã às 10h no lead #12345 para o Carlos."

Usar em outros clientes MCP

O servidor fala MCP por stdio, então funciona em qualquer cliente compatível. Exemplo de configuração genérica (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "kommo": {
      "command": "node",
      "args": ["/caminho/absoluto/para/kommo-mcp/index.mjs"]
    }
  }
}

Como o .env é lido a partir da pasta do servidor, não é necessário passar env no JSON (mas você pode, se preferir injetar KOMMO_SUBDOMAIN/KOMMO_TOKEN por ali).

Referência das tools

Datas aceitam ISO (2026-06-26T10:00) ou epoch. IDs de funil/etapa/usuário você descobre com kommo_pipelines e kommo_users. Listagens devolvem { items, page, has_more }; onde houver raw, raw: true devolve o payload cru da API.

Leitura

Auditoria

Atendimento & Inbox

Escrita em leads

Contatos & empresas

Funis/etapas

Webhooks

Campos personalizados

Catálogo, arquivos e automação

Genérico

* = obrigatório.

Estrutura do projeto

kommo-mcp/
├── index.mjs        # Servidor MCP: 41 tools, 4 prompts, 8 resources, transporte stdio
├── kommo.mjs        # Cliente HTTP (allowlist de hosts, retry/backoff, timeout, cache) + .env
├── smoke.mjs        # Teste end-to-end: sobe o server e valida contra a API real
├── package.json
├── .env.example     # Modelo das variáveis (copie para .env)
├── .gitignore       # Ignora .env e node_modules
├── LICENSE
└── README.md

Segurança

• Allowlist de hosts: o cliente HTTP só envia o token para {seu-subdomínio}.kommo.com e drive*.kommo.com. Mesmo que alguém induza o assistente a chamar kommo_request com uma URL externa (prompt injection via dados do CRM), o token não sai da infraestrutura da Kommo.

• Annotations MCP: leituras declaram readOnlyHint, escritas declaram destructiveHint, permitindo que o cliente aplique permissões distintas por protocolo.

• Nunca versione o .env (já protegido pelo .gitignore). Para compartilhar configuração, use o .env.example.

• O token tem os direitos de admin de quem o gerou — trate como senha.

• Se um token vazar, gere outro na Kommo: isso invalida o anterior imediatamente.

• Prefira o escopo mínimo (crm) ao criar a integração privada.

• Rode o servidor numa máquina/servidor sob seu controle.

Limitações conhecidas

• Salesbot nativo da Kommo: o fluxo/cenário do bot é editável apenas pela interface da Kommo. Pela API dá para ler tudo o que o bot fez (via kommo_get_events / notas) e dispará-lo num lead (kommo_run_salesbot) — mas não redesenhar o fluxo.

• Mensagens de chat (amojo): ler/enviar o conteúdo das conversas exige registrar um canal próprio na Chats API (credencial separada); está fora do escopo deste servidor.

• Módulo Customers: só funciona em contas com o módulo habilitado no plano (customers_mode diferente de disabled); alcançável via kommo_request se for o caso.

• v2.x muda o formato das listagens para { items, page, has_more } com itens resumidos (v1.x devolvia o array cru). Use raw: true onde precisar do payload original.

Troubleshooting

HTTP 401 Invalid user name or password O token foi rejeitado. Causas comuns:

• O subdomínio (KOMMO_SUBDOMAIN) e o token são de contas diferentes. Confirme o subdomínio na URL ao logar na Kommo (a parte antes de .kommo.com).

• A integração privada está desativada/em rascunho, ou você gerou um token novo depois (o que invalida o anterior). Gere um token novo e atualize o .env.

• O usuário que criou a integração não é mais admin ou foi desativado.

As tools não aparecem no Claude Code Reinicie o Claude Code após claude mcp add — servidores MCP só carregam no início da sessão. Confira com claude mcp get kommo.

Faltam KOMMO_SUBDOMAIN e/ou KOMMO_TOKEN O .env não foi encontrado ou está incompleto. Confirme que ele existe na raiz do projeto e tem as duas variáveis.

Deploy em servidor (VPS)

Como o transporte é stdio, o servidor roda sob demanda quando o cliente MCP o invoca — não precisa ficar de pé como serviço de rede. Para usar numa VPS:

git clone https://github.com/RonaldoESantosRevOps/kommo-mcp.git
cd kommo-mcp && npm install
cp .env.example .env   # preencha com seu subdomínio e token

E aponte o cliente MCP para o caminho do index.mjs nesse servidor.

Licença

MIT © Ronaldo E. Santos