Kommo MCP Server

Este é um servidor Model Context Protocol (MCP) que fornece integração nativa com o Kommo CRM (versão 4). Ele foi projetado para permitir que Assistentes de IA (como Claude Desktop, Cursor, entre outros) interajam de forma autônoma e inteligente com funis de vendas, leads e contatos.

🚀 Como Funciona

Esse servidor expõe ferramentas pré-definidas para interações comuns com o CRM, bem como uma "Super Ferramenta" (kommo_api_request) capaz de realizar qualquer requisição HTTP arbitrária para a REST API v4 do Kommo, tornando a evolução e o gerenciamento de funis incrivelmente ágeis.

---

🚀 Como instalar (Para quem NÃO É Dev)

Se você não sabe mexer com código ou terminal, não se preocupe! Você vai pedir para a sua Inteligência Artificial configurar tudo por você — basta seguir os 3 passos abaixo.

🚨 Pré-requisitos Obrigatórios — Faça isso antes de começar:

1. Node.js: O servidor precisa do Node para funcionar. Baixe e instale aqui (escolha a versão LTS).
2. Claude Desktop: Você precisa do aplicativo desktop do Claude instalado no seu computador. ⚠️ O Claude pelo navegador (claude.ai) não funciona para essa instalação, pois ele não consegue executar comandos no seu computador. → Baixe o Claude Desktop aqui

---

Passo 1: Tenha as suas Credenciais do Kommo

Acesse as configurações da sua conta Kommo em Integrações > Criar Integração Privada. Você vai precisar de:

1. Seu Subdomínio — ex: se o endereço é agenciadodavid.kommo.com, o subdomínio é agenciadodavid
2. Seu Bearer Token de longa duração (Long-lived Token)

Anote ou copie esses dois dados — você vai usá-los no Passo 3.

---

Passo 2: Baixe e salve a pasta do projeto

1. Acesse https://github.com/wdavidce/kommo-mcp-server
2. Clique no botão verde "Code" e depois em "Download ZIP"
3. Quando o download terminar, extraia (descompacte) a pasta
4. Mova a pasta para um local fixo e fácil de encontrar — sugerimos a pasta Documentos

---

Passo 3: Descubra o caminho da pasta no seu computador

Para a IA saber onde está a pasta, você precisa informar o caminho completo dela. Veja como descobrir:

🪟 Windows

1. Abra a pasta extraída no Explorador de Arquivos
2. Clique na barra de endereço no topo da janela (onde aparece o nome das pastas)
3. O caminho completo vai aparecer selecionado — copie ele

Exemplo de como vai aparecer: C:\Users\SeuNome\Documents\kommo-mcp-server

🍎 Mac

Opção 1 — Via Finder:

1. Clique com o botão direito na pasta
2. Selecione "Obter Informações"
3. Copie o caminho que aparece em "Onde:" e adicione /kommo-mcp-server no final

Opção 2 — Via Terminal (mais rápido):

1. Abra o Terminal
2. Digite echo (com espaço no final) e arraste a pasta direto para o Terminal
3. Pressione Enter — o caminho completo vai aparecer

Exemplo de como vai aparecer: /Users/seunome/Documents/kommo-mcp-server

---

Passo 4: Mande a IA fazer o trabalho pesado

Abra o Claude Desktop, faça o upload deste arquivo README.md e envie a mensagem abaixo, substituindo os campos indicados pelos seus dados:

---

"Olá! Eu baixei a pasta do servidor MCP do Kommo no GitHub e quero instalá-la aqui no meu computador para você ter acesso.

O caminho onde eu salvei a pasta é: [COLE_AQUI_O_CAMINHO_DA_PASTA].

O meu subdomínio do Kommo é: [SEU_SUBDOMINIO] e o meu Token de Longa Duração é: [SEU_TOKEN_AQUI].

Por favor, use as instruções do README que anexei para: 1. Instalar as dependências do Node (npm install). 2. Compilar o projeto (npm run build). 3. Injetar as configurações automaticamente no arquivo claude_desktop_config.json para adicionar esse MCP no sistema.

Me avise quando terminar."

---

A IA vai executar os comandos no seu terminal, modificar os arquivos necessários e deixar as ferramentas 100% ativadas.

⚠️ IMPORTANTE — Último passo obrigatório: Quando a IA avisar que terminou, você precisa fechar completamente o Claude Desktop e abrir de novo. Sem reiniciar, as ferramentas não vão aparecer. Após reabrir, procure o ícone de 🔧 ferramentas na interface — se aparecer, está funcionando!

---

💻 Instalação Manual Avançada (Para Devs)

Caso você prefira o controle total via terminal:

# 1. Instale as dependências
npm install

# 2. Compile o código TypeScript
npm run build

Adicione o JSON abaixo no arquivo global claude_desktop_config.json:

{
  "mcpServers": {
    "kommo-mcp": {
      "command": "node",
      "args": ["/CAMINHO_ABSOLUTO_DA_PASTA/build/index.js"],
      "cwd": "/CAMINHO_ABSOLUTO_DA_PASTA",
      "env": {
        "KOMMO_SUBDOMAIN": "seu_subdominio",
        "KOMMO_ACCESS_TOKEN": "seu_token"
      }
    }
  }
}

Reinicie o Claude Desktop.

---

🧰 O que a sua IA fará por você agora

A IA recebe acesso imediato a 27 ferramentas. Veja o resumo abaixo — para documentação completa com todos os parâmetros e comportamentos, consulte docs/tools.md.

Ferramenta	Categoria	Descrição resumida
search_leads	Busca	Busca leads por nome, telefone, e-mail, CPF etc.
search_contacts	Busca	Busca contatos no CRM.
get_lead	Leitura	Retorna todos os detalhes de um lead pelo ID.
get_contact	Leitura	Retorna todos os detalhes de um contato pelo ID.
list_users	Leitura	Lista todos os usuários. Útil para obter o responsible_user_id.
list_custom_fields	Estrutura	Lista campos personalizados de leads/contatos para mapeamento exato de IDs e Enums.
create_custom_field	Estrutura	Cria campos customizados avançados (selects, multiselects) com array de Enums.
update_custom_field	Estrutura	Edita um campo customizado existente (ex: mudar de nome).
create_webhook	Automação	Assina o n8n/webhook para escutar eventos em tempo real do CRM.
run_salesbot	Automação	Executa um robô de funil para um lead específico (gatilho).
link_entities	Estrutura	Vincula explicitamente entidades (ex: ligar um Contato a um Lead existente).
get_companies	Leitura	Traz a lista de empresas focadas para o mercado corporativo (B2B).
create_company	Criação	Cria entidades para gerir vendas tipo B2B.
create_task	Operacional	Cria uma tarefa (ligação, reunião, e-mail) para um lead ou contato.
add_lead_note	Operacional	Adiciona uma nota de texto rica à aba de histórico do lead.
create_lead_complex	Criação	Cria lead + contato com campos customizados. Evita duplicatas automaticamente.
update_lead	Atualização	Atualiza campos de um lead existente.
update_contact	Atualização	Atualiza dados de um contato existente.
manage_lead_tags	Atualização	Adiciona/remove tags de um lead sem sobrescrever as existentes.
get_pipelines	Funil	Lista todos os funis e suas etapas.
get_pipeline_statuses	Funil	Lista etapas de um funil com descrições (dicas) por nível de usuário.
create_pipeline	Funil	Cria um novo funil de vendas.
add_pipeline_stage	Funil	Adiciona uma nova etapa a um funil existente.
rename_pipeline	Funil	Renomeia um funil.
rename_pipeline_stage	Funil	Atualiza nome, cor, posição e/ou descrições de uma etapa. Preserva automaticamente sort e color se omitidos.
kommo_api_request	Super Tool	Envia qualquer requisição HTTP arbitrária à API v4 do Kommo.
send_whatsapp_message	Comunicação	Envia mensagem de WhatsApp via integração Kommo.

📖 Documentação detalhada: docs/tools.md

---

💡 Casos de Uso com a IA

Uma vez conectado, você não precisará abrir o painel do Kommo para fazer gerenciamento estratégico. Exemplos de prompts que farão a API trabalhar por você:

• "Faça um dump estrutural de todos os meus funis e me diga quais as etapas e IDs deles."
• "Pesquise o contato do William no Kommo e me diga qual foi o ticket médio e os dados do último pedido (Campos Customizados)."
• "Crie uma nova etapa chamada 'Retenção' no funil Principal com a cor #fffd7f em último lugar (sort)."
• "Renomeie a etapa 'Negociação (IA)' para 'Montando Carrinho'."
• "Atualize a descrição da etapa 'Pedido Criado' para o nível newbie."

---

🧑‍💻 Adicionando Novas Ferramentas

Caso necessite engessar uma funcionalidade específica para evitar que a IA crie o payload sozinha toda vez:

1. Abra src/index.ts
2. Adicione os meta-dados da nova ferramenta e os parâmetros desejados dentro do array em ListToolsRequestSchema
3. Escreva a regra de negócios (request para API) no seletor de ações dentro de CallToolRequestSchema
4. Rode npm run build e reinicie o Claude Desktop