kommo-integration-mcp

Servidor MCP que fecha o loop entre o Mapeador de Funil (a IA que desenha o funil) e o Kommo CRM: você valida o funil gerado e, com aprovação explícita, uma IA cria o pipeline, as etapas e os campos personalizados diretamente no Kommo — sem trabalho manual na interface do CRM.

Suporta múltiplos clientes/contas Kommo num único servidor: cada chamada informa qual cliente usar, então basta cadastrar credenciais uma vez em clients.json — sem reiniciar nada ao adicionar um cliente novo.

Fluxo

1. O Mapeador de Funil gera um JSON no formato descrito abaixo.
2. Você (ou a IA, via validate_funnel/preview_funnel) revisa etapas e campos.
3. A IA confirma qual cliente é (via list_clients).
4. Com o JSON aprovado, create_funnel (com confirm: true) cria tudo no Kommo daquele cliente.

Ferramentas MCP expostas

Ferramenta	O que faz	Grava no Kommo?
list_clients	Lista os clientes cadastrados em clients.json (chave, nome, subdomínio)	Não
validate_funnel	Valida o JSON do funil contra o schema, retorna erros/avisos	Não
preview_funnel	Gera um resumo legível do que será criado	Não
list_pipelines	Lista funis já existentes na conta de um cliente (evita duplicar)	Não
list_custom_fields	Lista campos personalizados já existentes por entidade de um cliente	Não
create_funnel	Cria o pipeline + etapas + campos personalizados para um cliente. Exige confirm: true	Sim

list_pipelines, list_custom_fields e create_funnel recebem um parâmetro client com a chave cadastrada em clients.json (ex: "cliente-a").

Formato do funil (contrato de entrada)

{
  "name": "Funil de Vendas - Novos Clientes",
  "stages": [
    { "name": "Novo lead", "color": "#99ccff" },
    { "name": "Contato realizado" },
    { "name": "Proposta enviada" }
  ],
  "fields": [
    {
      "name": "Origem do lead",
      "type": "select",
      "entity": "leads",
      "required": true,
      "options": ["Site", "Indicação", "Anúncio pago"]
    }
  ]
}

Veja um exemplo completo em examples/funnel.example.json.

Notas:

• O Kommo sempre cria automaticamente a etapa "Entrada de leads" no início e "Ganho"/"Perdido" no fim de todo pipeline — declare só as etapas intermediárias.
• color é opcional (hex, ex: #99ccff); se omitido o Kommo usa uma cor padrão.
• Tipos de campo suportados: text, textarea, numeric, checkbox, select, multiselect, date, url, radiobutton. select/multiselect/radiobutton exigem options.
• entity define onde o campo aparece: leads (padrão), contacts, companies ou customers.

Setup

1. Instalar e buildar

npm install
npm run build

2. Cadastrar os clientes

Copie o exemplo e preencha um bloco por cliente:

cp clients.example.json clients.json

// clients.json
{
  "cliente-a": {
    "label": "Cliente A Ltda",
    "subdomain": "clientea",       // clientea.kommo.com
    "accessToken": "token-de-longa-duracao-do-cliente-a"
  },
  "cliente-b": {
    "label": "Cliente B S.A.",
    "subdomain": "clienteb",
    "accessToken": "token-de-longa-duracao-do-cliente-b"
  }
}

O token de longa duração de cada conta é gerado em: Kommo → Configurações → Integrações → sua integração → "Token de longa duração".

Para adicionar um cliente novo depois, só edite clients.json e chame list_clients de novo — não precisa reiniciar o servidor nem o Claude Desktop.

clients.json já está no .gitignore: nunca commite esse arquivo, ele concentra os tokens de todos os clientes.

3. Registrar o servidor MCP no Claude

No claude_desktop_config.json (ou config equivalente do Claude Code):

{
  "mcpServers": {
    "kommo-integration": {
      "command": "node",
      "args": ["/caminho/absoluto/para/kommo-integration-mcp/dist/index.js"]
    }
  }
}

Por padrão o servidor procura clients.json na raiz do projeto. Para usar outro caminho (ex: um cofre de segredos fora do repositório), defina KOMMO_CLIENTS_FILE:

{
  "mcpServers": {
    "kommo-integration": {
      "command": "node",
      "args": ["/caminho/absoluto/para/kommo-integration-mcp/dist/index.js"],
      "env": {
        "KOMMO_CLIENTS_FILE": "/caminho/seguro/clients.json"
      }
    }
  }
}

Reinicie o Claude Desktop/Code. As ferramentas list_clients, validate_funnel, preview_funnel, list_pipelines, list_custom_fields e create_funnel ficam disponíveis na conversa.

Desenvolvimento

npm run dev         # roda via tsx sem build
npm run typecheck    # checagem de tipos
npm run build         # compila para dist/

Segurança

• create_funnel só executa se o parâmetro confirm vier true — trate isso como o "sim, pode criar" do humano que validou o funil.
• Cada token de longa duração dá acesso total à respectiva conta Kommo conforme as permissões da integração. clients.json concentra os tokens de todos os clientes — trate como segredo (já está no .gitignore; considere restringir permissões do arquivo, ex: chmod 600 clients.json).