Kommo MCP Server

Servidor MCP (Model Context Protocol) para integração com o Kommo CRM. Expõe tools, resources e prompts para clientes MCP (Cursor, Claude, etc.).

Funcionalidades

• Protocolo MCP v2: Lifecycle, transporte Streamable HTTP, validação de headers (MCP-Protocol-Version, MCP-Session-Id)

• 23 Tools: Leads, contatos, empresas, tarefas, pipelines, notas, relatórios, dashboard, Salesbot, motivos de perda

• 5 Resources: Relatório de vendas, pipelines, motivos de perda, dashboard, conta

• 4 Prompts: Templates para análise de vendas, leads, pipelines e motivos de perda

• ask_kommo: Interface conversacional em linguagem natural

• Arquitetura modular: Código organizado em módulos (kommo-api, mcp/, ask-kommo)

• Segurança: Validação de Origin, bind em localhost por default, autenticação opcional

Related MCP server: Kommo MCP Server

Pré-requisitos

• Node.js 20+

• Docker (opcional)

• Token de acesso do Kommo (integração privada ou OAuth2)

Configuração

1. Copie o arquivo de exemplo:

cp env.example .env

2. Configure no .env:

KOMMO_BASE_URL=https://seu-dominio.kommo.com
KOMMO_ACCESS_TOKEN=seu-token-aqui

Variáveis opcionais:

Execução

Desenvolvimento:

npm install
npm run build
npm start

Docker:

docker build -t kommo-mcp-server .
docker run -d -p 3001:3001 --name kommo-mcp-server kommo-mcp-server

O servidor sobe em http://127.0.0.1:3001 (ou MCP_HOST:PORT).

Endpoints

• MCP: POST http://localhost:3001/mcp — JSON-RPC (initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get)

• Health: GET http://localhost:3001/health

Ferramentas MCP

Conta e Dashboard

Leads

Pipelines e Relatórios

Contatos, Empresas e Tarefas

Notas

Motivos de Perda e Salesbot

IA Conversacional

Resources

Prompts

Estrutura do Projeto

src/
├── kommo-api.ts          # Cliente da API Kommo
├── ask-kommo.ts          # Lógica conversacional ask_kommo
├── http-streamable.ts    # Servidor MCP HTTP
└── mcp/
    ├── types.ts          # Tipos MCP
    ├── tool-definitions.ts  # Schemas das tools
    ├── tool-handlers.ts  # Execução das tools
    ├── resources.ts      # Resources MCP
    └── prompts.ts        # Prompts MCP

Exemplos de uso

1. Inicializar sessão MCP:

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1.0.0"}}}'

2. Listar ferramentas:

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. Mover lead para outro status:

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"move_lead","arguments":{"lead_id":12345,"status_id":142}}}'

4. Adicionar nota a um lead:

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"add_note","arguments":{"entity_type":"leads","entity_id":12345,"text":"Cliente interessado no plano premium"}}}'

Documentação

• docs/MCP_EVOLUCAO.md — Plano de evolução e conformidade MCP

• docs/KOMMO_API_EVOLUCAO.md — Evoluções da API Kommo

• Kommo para desenvolvedores

• Changelog Kommo

Changelog

v2.0.0

• Arquitetura modular (separação em mcp/, ask-kommo.ts)

• 11 novas tools: get_account, get_lead, update_lead, move_lead, get_pipelines, get_dashboard, create_task, get_users, get_loss_reason, get_notes, add_note

• 2 novos resources: kommo://dashboard, kommo://account

• 2 novos prompts: analise_pipeline, motivos_perda

• API de notas: listar e criar notas

• Remoção de valores hardcoded e código duplicado

• env.example sanitizado (sem tokens reais)

Licença

MIT