# Kommo MCP Server

Este é um servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://nodejs.org/) (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](https://claude.ai/download)

---

### 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](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:

```bash
# 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`:

```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`](./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`](./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