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.

📖 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