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

29 tools divididas em:

A referência completa de parâmetros está mais abaixo.

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: 29
✓ kommo_account -> <Nome da sua conta> (id ..., BRL)
✓ kommo_pipelines -> N funis; principal: ...
✓ kommo_users -> N usuários: ...
✓ kommo_search_leads(limit 3) -> 3 leads
✓ kommo_get_events(created_by=0, limit 5) -> 5 eventos de bot/sistema
✓ SMOKE OK

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"
    ]
  }
}

Todas as tools de escrita (criar/editar leads, contatos, empresas, tarefas, notas, etapas, campos custom, vínculos e webhooks) e o passthrough kommo_request continuam pedindo confirmação — o comportamento seguro recomendado.

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.

Leitura

Auditoria

Escrita

Contatos & empresas

Funis/etapas

Webhooks

Campos personalizados

Genérico

* = obrigatório.

Estrutura do projeto

kommo-mcp/
├── index.mjs        # Servidor MCP: define as 29 tools e o transporte stdio
├── kommo.mjs        # Cliente HTTP da API v4 + carregador de .env (sem dependências extras)
├── smoke.mjs        # Teste end-to-end: sobe o server e chama tools de leitura
├── package.json
├── .env.example     # Modelo das variáveis (copie para .env)
├── .gitignore       # Ignora .env e node_modules
├── LICENSE
└── README.md

Segurança

• 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, via kommo_request, disparar/parar — mas não redesenhar o fluxo.

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