Kommo

License: MIT Node.js 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

---

Recursos

41 tools, 4 prompts e 8 resources MCP:

Categoria	Tools
Leitura	kommo_account, kommo_pipelines, kommo_users (com is_active), kommo_custom_fields, kommo_search_leads, kommo_get_lead, kommo_list_tasks, kommo_search_contacts, kommo_search_companies, kommo_list_webhooks, kommo_tags, kommo_loss_reasons, kommo_catalog_elements
Auditoria	kommo_get_events (feed traduzido: etapas/autores por nome; created_by=0 = bot/automação)
Atendimento	kommo_talks (fila de conversas em tempo real), kommo_close_talk, kommo_unsorted (Inbox), kommo_unsorted_accept, kommo_unsorted_decline
Leads	kommo_create_lead, kommo_update_lead (com tags), kommo_change_responsible, kommo_bulk_update_leads (lote com fatiamento)
Tarefas & notas	kommo_create_task (tipos reais da conta na descrição), kommo_complete_task, kommo_add_note (common/call_in/call_out)
Contatos & empresas	kommo_create_contact, kommo_update_contact, kommo_create_company, kommo_update_company, kommo_link (inclui catalog_elements)
Funis/etapas	kommo_create_status, kommo_update_status
Webhooks	kommo_subscribe_webhook, kommo_delete_webhook
Campos custom	kommo_create_custom_field, kommo_update_custom_field (com add_enums)
Catálogo & arquivos	kommo_create_catalog_element, kommo_upload_file
Automação	kommo_run_salesbot (dispara bot num lead; sempre confirme antes)
Genérico	kommo_request (passthrough autenticado, restrito a hosts *.kommo.com da conta)

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):

Escopo	Onde vale	Quando usar
user	Todos os seus projetos	Recomendado — você usa a mesma conta Kommo em qualquer lugar
project	Compartilhado no repositório (.mcp.json)	Se um time inteiro vai usar
local	Só você, só neste projeto	Testes pontuais

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

Tool	Parâmetros principais	O que faz
kommo_account	—	Dados da conta (confirma a conexão).
kommo_pipelines	—	Lista funis e suas etapas (id, name, sort, type).
kommo_users	—	Lista usuários com is_active/is_admin (não atribua a inativos).
kommo_custom_fields	entity (leads/contacts/companies)	Lista campos personalizados e seus id.
kommo_search_leads	query, pipeline_id, status_id (resolve o funil sozinho), responsible_user_id, created_from/to, updated_from/to, order_by, fields[], raw, limit, page	Busca leads resumidos (funil/etapa/responsável por nome, telefone, tags, motivo de perda).
kommo_get_lead	lead_id*, note_limit	Detalhe cru de um lead (contatos, catálogo, motivo de perda); anexa notas se note_limit>0.
kommo_list_tasks	responsible_user_id, entity_id, entity_type, is_completed, limit, page	Lista tarefas resumidas.
kommo_search_contacts	query, raw, limit, page	Busca contatos (telefone/email extraídos).
kommo_search_companies	query, raw, limit, page	Busca empresas.
kommo_list_webhooks	—	Lista os webhooks configurados (destino e eventos).
kommo_tags	entity, query, limit, page	Lista tags (id, nome, cor).
kommo_loss_reasons	—	Lista os motivos de perda configurados.
kommo_catalog_elements	catalog_id*, query, limit, page	Lista elementos de um catálogo (produtos/serviços).

Auditoria

Tool	Parâmetros principais	O que faz
kommo_get_events	entity, entity_id, type[], created_by[], from, to, raw, limit, page	Feed de eventos traduzido (etapas e autores por nome, datas no fuso da conta). created_by=0 = ações de bot/automação.

Atendimento & Inbox

Tool	Parâmetros principais	O que faz
kommo_talks	is_in_work, is_read, contact_id, limit, page	Fila de conversas (chats) em tempo real.
kommo_close_talk	talk_id*, force_close	Fecha uma conversa.
kommo_unsorted	category, pipeline_id, summary, limit, page	Inbox de leads não distribuídos (summary: true = agregado).
kommo_unsorted_accept	uid*, user_id, status_id	Aceita um item do Inbox (vira lead ativo).
kommo_unsorted_decline	uid*, user_id	Rejeita um item do Inbox (difícil de desfazer).

Escrita em leads

Tool	Parâmetros principais	O que faz
kommo_create_lead	name*, price, pipeline_id, status_id, responsible_user_id, contact_name, contact_phone, tags[], custom_fields_values	Cria lead; vincula contato se informado.
kommo_update_lead	lead_id*, name, price, status_id, pipeline_id, responsible_user_id, loss_reason_id, tags_to_add[], tags_to_remove[], custom_fields_values	Atualiza lead; tags são mescladas preservando as existentes.
kommo_change_responsible	lead_ids[], responsible_user_id	Troca o responsável em lote (fatiamento automático).
kommo_bulk_update_leads	lead_ids[]*, status_id, pipeline_id, responsible_user_id, price, loss_reason_id, tags_to_add[]	Atualização em massa com blocos de 200 e relatório de sucesso/falha.
kommo_add_note	entity_id, text, entity, note_type (common/call_in/call_out), params_extra	Adiciona nota ou registro de ligação.
kommo_create_task	text*, entity_id, entity, complete_till, responsible_user_id, task_type_id (tipos reais da conta na descrição)	Cria tarefa (prazo padrão: +1 dia).
kommo_complete_task	task_id*, result	Conclui uma tarefa com resultado opcional.

Contatos & empresas

Tool	Parâmetros principais	O que faz
kommo_create_contact	name/first_name/last_name, phone, email, responsible_user_id, custom_fields_values	Cria contato (telefone/email viram campos PHONE/EMAIL).
kommo_update_contact	contact_id*, name, responsible_user_id, custom_fields_values	Atualiza um contato.
kommo_create_company	name*, responsible_user_id, custom_fields_values	Cria empresa.
kommo_update_company	company_id*, name, responsible_user_id, custom_fields_values	Atualiza uma empresa.
kommo_link	entity, entity_id, to_entity_type* (inclui catalog_elements), to_entity_id*, catalog_id, quantity	Vincula entidades, inclusive produto/procedimento a lead.

Funis/etapas

Tool	Parâmetros principais	O que faz
kommo_create_status	pipeline_id, name, sort, color	Cria uma etapa num funil.
kommo_update_status	pipeline_id, status_id, name, sort, color	Renomeia/reordena/recolore uma etapa.

Webhooks

Tool	Parâmetros principais	O que faz
kommo_subscribe_webhook	destination* (URL), settings* (eventos)	Assina eventos da Kommo numa URL.
kommo_delete_webhook	destination*	Cancela um webhook pela URL.

Campos personalizados

Tool	Parâmetros principais	O que faz
kommo_create_custom_field	entity, name*, type, enums	Cria campo custom (use enums para select/multiselect).
kommo_update_custom_field	entity, field_id*, name, add_enums[]	Renomeia e/ou acrescenta opções a um select preservando as existentes.

Catálogo, arquivos e automação

Tool	Parâmetros principais	O que faz
kommo_create_catalog_element	catalog_id, name, custom_fields_values	Cria um elemento (ex.: procedimento com preço).
kommo_upload_file	file_path*, file_name, entity, entity_id	Sobe arquivo ao drive e anexa à entidade, se informada.
kommo_run_salesbot	bot_id, entity_id, entity_type	Dispara um Salesbot num lead (envia mensagens reais). Confirme sempre.

Genérico

Tool	Parâmetros principais	O que faz
kommo_request	method, path*, query, body	Chamada autenticada a qualquer endpoint; restrita a hosts *.kommo.com da conta.

* = 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