What can you do with this server?

The Kommo CRM MCP Server integrates with Kommo CRM via the Model Context Protocol, exposing tools, resources, and prompts to MCP clients like Cursor and Claude. CRM Data Access * Retrieve account info, leads, contacts, companies, tasks, pipelines, and users (with pagination up to 250/page) Lead & Pipeline Management * Create leads, get/create pipeline statuses, move leads between statuses or pipelines Events & Activities * Get and create events for leads; get and create activities for contacts Notes & Automation * Pin/unpin notes on entities; start/stop Salesbot automation Reporting & Analytics * Sales reports, lead conversion reports, pipeline performance reports, dashboard KPIs, user performance stats, and per-lead/per-pipeline analytics — all over custom date ranges Loss Reasons * Access lead loss reasons Conversational AI * Use the ask_kommo tool to query CRM data in natural language MCP Compliance * Full MCP lifecycle support, streamable HTTP transport, header validation, optional authentication, plus pre-defined resources and prompt templates for sales analysis and lead summaries

Which integrations are available for this server?

Provides integration capabilities with n8n workflow automation platform through MCP Client Tool, enabling automated CRM workflows and data synchronization

How do I use Kommo CRM MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Kommo CRM MCP Server show me sales performance for this quarter" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Related MCP server: Attio MCP Server

Funcionalidades

Protocolo MCP: Lifecycle (initialize / initialized), transporte Streamable HTTP, validação de headers (MCP-Protocol-Version, MCP-Session-Id)
Tools: Leads, contatos, empresas, tarefas, relatório de vendas, criação de lead, motivos da perda, fixar/desafixar notas, Salesbot (run/stop)
Resources: Relatório de vendas, pipelines, motivos da perda de leads
Prompts: Templates para análise de vendas e resumo de leads
ask_kommo: Interface conversacional (perguntas em linguagem natural sobre vendas, leads, contatos)
Segurança: Validação de Origin, bind em localhost por default, autenticação opcional

Pré-requisitos

Node.js 20+
Docker (opcional)
Token de acesso do Kommo (integração privada ou OAuth2)

Configuração

Copie o arquivo de exemplo:

cp env.example .env

Configure no .env:

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

Variáveis opcionais:

Variável	Descrição	Default
`MCP_HOST`	Host de binding	`127.0.0.1`
`MCP_ALLOWED_ORIGINS`	Origens permitidas (separadas por vírgula)	—
`MCP_AUTH_TOKEN`	Se definido, exige `Authorization: Bearer` ou `X-API-Key` no `/mcp`	—

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

Tool	Descrição
`get_leads`	Listar leads (limit, page)
`create_lead`	Criar lead (name, price, status_id)
`get_sales_report`	Relatório de vendas (dateFrom, dateTo)
`get_contacts`	Listar contatos
`get_companies`	Listar empresas
`get_tasks`	Listar tarefas
`get_loss_reasons`	Listar motivos da perda de leads (API 2026)
`pin_note`	Fixar nota (entity_type, note_id)
`unpin_note`	Desafixar nota (entity_type, note_id)
`run_salesbot`	Iniciar Salesbot (entity_id, entity_type)
`stop_salesbot`	Parar Salesbot (bot_id)
`ask_kommo`	Perguntas em linguagem natural sobre o CRM

Resources

kommo://reports/sales — Relatório de vendas (último mês)
kommo://pipelines — Lista de pipelines
kommo://loss_reasons — Motivos da perda de leads

Exemplos de uso

1. Inicializar sessão MCP (obrigatório para clientes conformes):

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. Pergunta conversacional:

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":"ask_kommo","arguments":{"question":"quantas vendas tivemos este mês?"}}}'

4. Motivos da perda de leads:

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":"get_loss_reasons","arguments":{}}}'

Documentação

docs/MCP_EVOLUCAO.md — Plano de evolução e conformidade MCP
docs/KOMMO_API_EVOLUCAO.md — Evoluções da API Kommo e benefícios para o MCP

Migração opcional para o SDK MCP

O servidor implementa o protocolo MCP manualmente. Para migrar para o SDK oficial (@modelcontextprotocol/sdk): use Server e SSEServerTransport de @modelcontextprotocol/sdk/server (e server/sse), monte o transport no Express e registre handlers com setRequestHandler, delegando à mesma lógica de negócio (KommoAPI em src/kommo-api.ts).