Kommo CRM MCP Server
An MCP server for Kommo CRM that enables querying CRM data, managing leads/activities/statuses, and generating sales/performance reports.
Retrieve account info, leads, contacts, companies, tasks, pipelines, users, lead events, and contact activities.
Create lead events, contact activities, and pipeline statuses.
Move leads between statuses and pipelines.
Generate sales, lead conversion, pipeline performance, dashboard, user performance, lead analytics, and pipeline analytics reports.
Also documents MCP resources and prompts for sales, pipeline, lead, and loss-reason analysis.
Provides integration capabilities with n8n workflow automation platform through MCP Client Tool, enabling automated CRM workflows and data synchronization
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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 Desktop, etc.).
Sumário
Related MCP server: Bitrix24 MCP Server
Funcionalidades
MCP moderno e compatível: revisão
2026-07-28pelo SDK oficial, com compatibilidade stateless para clientes da família 2025Dois transportes oficiais: Streamable HTTP para serviços remotos e
stdiopara clientes locais23 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 naturalArquitetura modular: código organizado em módulos (
kommo-api,mcp/,ask-kommo)Segurança: validação de Origin, validação dos argumentos das tools e autenticação obrigatória fora de localhost
Pré-requisitos
Node.js 22.13+
Docker (opcional)
Token de acesso do Kommo (integração privada ou OAuth2) — ver documentação do Kommo
Início rápido
git clone https://github.com/Miguelgbastos/Kommo-MCP.git
cd Kommo-MCP
npm install
cp env.example .env
# edite .env com KOMMO_BASE_URL e KOMMO_ACCESS_TOKEN
npm run build
npm startO servidor sobe em http://127.0.0.1:3001/mcp.
Configuração
Copie o arquivo de exemplo:
cp env.example .envConfigure no
.env:KOMMO_BASE_URL=https://seu-dominio.kommo.com KOMMO_ACCESS_TOKEN=seu-token-aqui
Variáveis de ambiente
Variável | Descrição | Default |
| URL da conta Kommo ( | — |
| Token de acesso (integração privada ou OAuth2) | — |
| Timeout de cada requisição ao Kommo |
|
| Retentativas de leituras em |
|
| Limite coordenado de chamadas por processo (máximo 6) |
|
| Fuso IANA dos relatórios; por padrão usa o fuso da conta | conta Kommo |
| Porta HTTP do servidor MCP |
|
| Host de binding |
|
| Origens permitidas (separadas por vírgula) | — |
| Protege | — |
| Limite de requisições ao |
|
| Exige |
|
| Nível de log |
|
Execução
Desenvolvimento:
npm install
npm run dev # ts-node
# ou
npm run build && npm startCliente local via stdio:
npm run build
npm run start:stdioDocker:
docker build -t kommo-mcp-server .
docker run -d -p 3001:3001 \
-e KOMMO_BASE_URL=https://seu-dominio.kommo.com \
-e KOMMO_ACCESS_TOKEN=seu-token \
-e MCP_HOST=0.0.0.0 \
-e MCP_AUTH_TOKEN=gere-um-segredo-longo \
--name kommo-mcp-server kommo-mcp-serverEm produção, coloque o servidor atrás de um reverse proxy com TLS e defina
MCP_AUTH_TOKEN+MCP_ALLOWED_ORIGINS. O servidor se recusa a iniciar em um endereço não local semMCP_AUTH_TOKEN, inclusive quandocreateApp()é usado diretamente. A imagem Docker usa127.0.0.1por padrão; para publicar a porta, configure conscientementeMCP_HOST=0.0.0.0junto com um token longo.
A confirmação explícita é obrigatória por padrão nas tools de escrita. Use
MCP_CONFIRM_WRITES=falsesomente em automações controladas que assumam esse risco; o servidor registra um aviso operacional quando essa proteção é desativada. As tools de escrita anunciamdestructiveHint; as consultas anunciamreadOnlyHintpelo protocolo MCP.
Integração com clientes MCP
Cursor
O pacote npm ainda não foi publicado. Até a release v3, compile o projeto e
adicione ao ~/.cursor/mcp.json o caminho absoluto do arquivo gerado:
{
"mcpServers": {
"kommo": {
"command": "node",
"args": ["/caminho/absoluto/Kommo-MCP/dist/stdio.js"],
"env": {
"KOMMO_BASE_URL": "https://seu-dominio.kommo.com",
"KOMMO_ACCESS_TOKEN": "seu-token-aqui"
}
}
}
}Para o servidor HTTP:
Adicione ao arquivo ~/.cursor/mcp.json (ou nas configurações do projeto em
.cursor/mcp.json):
{
"mcpServers": {
"kommo": {
"url": "http://127.0.0.1:3001/mcp"
}
}
}Claude Desktop
Para uma implantação remota com HTTPS, abra Settings → Connectors → Add
connector e informe a URL pública do endpoint, por exemplo
https://mcp.seudominio.com/mcp.
Para execução local, use a mesma configuração command/args/env acima no
claude_desktop_config.json. Servidores HTTP remotos devem ser adicionados
pela tela de Connectors.
Endpoints
MCP:
POST http://localhost:3001/mcp— negociação moderna viaserver/discoverHealth:
GET http://localhost:3001/healthReadiness:
GET http://localhost:3001/ready— verifica se URL e token obrigatórios foram configurados
Ferramentas MCP
Conta e dashboard
Tool | Descrição |
| Informações da conta Kommo |
| Dashboard calculado com endpoints públicos do Kommo |
Leads
Tool | Descrição |
| Listar leads ( |
| Obter lead por ID |
| Criar lead ( |
| Atualizar lead existente |
| Mover lead para outro status/pipeline |
Pipelines e relatórios
Tool | Descrição |
| Listar pipelines (com status opcional por |
| Relatório de vendas ( |
Contatos, empresas e tarefas
Tool | Descrição |
| Listar contatos |
| Listar empresas |
| Listar tarefas |
| Criar tarefa vinculada a entidade |
| Listar usuários da conta |
Notas
Tool | Descrição |
| Listar notas de lead/contato/empresa |
| Adicionar nota de texto |
| Fixar nota |
| Desafixar nota |
Motivos de perda e Salesbot
Tool | Descrição |
| Listar motivos da perda de leads |
| Obter motivo de perda por ID |
| Iniciar Salesbot ( |
| Parar Salesbot ( |
IA conversacional
Tool | Descrição |
| Perguntas em linguagem natural sobre o CRM |
Resources
URI | Descrição |
| Relatório de vendas (último mês) |
| Lista de pipelines |
| Motivos da perda de leads |
| Dados do dashboard |
| Informações da conta |
Prompts
Nome | Descrição |
| Analisar vendas do mês |
| Resumo de leads por status |
| Analisar performance de pipeline |
| Analisar motivos de perda |
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
├── stdio.ts # Servidor MCP local por stdin/stdout
└── mcp/
├── server.ts # Definição oficial do servidor 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 MCPExemplos de uso
Clientes compatíveis negociam a revisão automaticamente por server/discover.
Ao usar o cliente TypeScript oficial, fixe a revisão para evitar fallback
silencioso para servidores antigos:
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
const client = new Client(
{ name: 'minha-integracao', version: '1.0.0' },
{ versionNegotiation: { mode: { pin: '2026-07-28' } } },
);
const transport = new StreamableHTTPClientTransport(new URL('http://127.0.0.1:3001/mcp'));
await client.connect(transport);
const { tools } = await client.listTools();Clientes da família 2025 são atendidos automaticamente pelo modo stateless.
Clientes modernos podem fixar 2026-07-28 conforme o exemplo acima.
Troubleshooting
401 Unauthorizedda API do Kommo — verifique seKOMMO_ACCESS_TOKENestá válido e seKOMMO_BASE_URLaponta para o subdomínio correto da sua conta.Cliente MCP não conecta — confirme se
MCP_HOSTpermite conexões do cliente (0.0.0.0para acesso remoto) e seMCP_ALLOWED_ORIGINSinclui a origem do cliente, quando definido.403no/mcp— seMCP_AUTH_TOKENestiver definido, é preciso enviarAuthorization: Bearer <token>ouX-API-Key: <token>.503no/ready— configureKOMMO_BASE_URLcom HTTPS e definaKOMMO_ACCESS_TOKENantes de iniciar o serviço real.429do Kommo — todas as chamadas compartilham um limitador coordenado; leituras usam backoff eRetry-After, enquanto escritas não são repetidas automaticamente para evitar duplicidade.429do/mcp— o servidor limita cada endereço cliente a 120 requisições por minuto por processo; ajusteMCP_RATE_LIMIT_PER_MINUTEse necessário. O endereço do proxy é usado por padrão, poistrust proxynão é habilitado automaticamente.Docker
HEALTHCHECKfalha — a imagem usanode --evalpara o healthcheck, verifique se a porta interna corresponde aPORT.Erros de build TypeScript — rode
npm run typecheckpara ver mensagens detalhadas. Requer Node.js 22.13+.
Documentação
docs/MCP_EVOLUCAO.md — plano de evolução e conformidade MCP
docs/KOMMO_API_EVOLUCAO.md — evoluções da API Kommo
CHANGELOG.md deste projeto
ROADMAP.md — prioridades e oportunidades de contribuição
MAINTAINERS.md — manutenção, revisão e releases
docs/COMPATIBILITY.md — matriz automatizada e checklist de validação manual em clientes MCP
Compatibilidade e suporte
Componente | Suporte atual |
Node.js | 22.13+; CI em Node 22 e 24 |
Protocolo MCP |
|
Transporte | Streamable HTTP e stdio oficiais |
Cursor | stdio local ou HTTP |
Claude Desktop | stdio local ou conector remoto |
Instalação | Git e Docker; npm após a release v3 |
Suporte comunitário ocorre por Issues e Discussions, sem garantia de tempo de resposta. Veja as responsabilidades em MAINTAINERS.md.
Contribuindo
Contribuições são muito bem-vindas! Leia o CONTRIBUTING.md para o fluxo completo e o Código de Conduta para as regras da comunidade.
Sugestões rápidas:
Abra uma issue usando os templates.
Envie um PR pequeno e focado, com descrição do que muda e por quê.
Rode
npm run typecheck,npm run lint,npm test,npm run format:checkenpm run audit:prodantes de enviar.
Segurança
Para reportar vulnerabilidades, envie um e-mail para miguel.bastos@cosolutions.com.br. O processo está em SECURITY.md. Não abra issues públicas para problemas de segurança.
Licença
Distribuído sob a licença MIT.
Available Tools
22 toolscreate_contact_activityC
Create a new activity for a contact
Inputs: contact_id (required), type (required), responsible_user_id, text.
create_lead_eventC
Create a new event for a lead
Inputs: lead_id (required), type (required), responsible_user_id, text.
create_lead_statusC
Create a new status for a pipeline
Inputs: name (required), pipeline_id (required), color, sort.
get_account_infoC
Get Kommo account information
Inputs: no named parameters.
get_companiesC
Get list of companies from Kommo CRM
Inputs: limit, page.
get_contact_activitiesC
Get activities for a specific contact
Inputs: contact_id (required), limit, page.
get_contactsC
Get list of contacts from Kommo CRM
Inputs: limit, page.
get_dashboard_dataC
Get dashboard data and key metrics
Inputs: no named parameters.
get_lead_analyticsC
Get analytics for a specific lead
Inputs: lead_id (required).
get_lead_conversion_reportB
Get lead conversion report for a date range
Inputs: date_from (required), date_to (required).
get_lead_eventsC
Get events for a specific lead
Inputs: lead_id (required), limit, page.
get_leadsC
Get list of leads from Kommo CRM
Inputs: limit, page.
get_lead_statusesC
Get statuses for a specific pipeline
Inputs: pipeline_id (required).
get_pipeline_analyticsC
Get analytics for a specific pipeline
Inputs: pipeline_id (required), date_from, date_to.
get_pipeline_performance_reportC
Get pipeline performance report for a date range
Inputs: date_from (required), date_to (required).
get_pipelinesB
Get list of pipelines from Kommo CRM
Inputs: no named parameters.
get_sales_reportC
Get sales report for a date range
Inputs: date_from (required), date_to (required).
get_tasksC
Get list of tasks from Kommo CRM
Inputs: limit, page.
get_user_performance_statsC
Get performance statistics for a specific user
Inputs: user_id (required), date_from, date_to.
get_usersB
Get list of users from Kommo CRM
Inputs: no named parameters.
move_lead_to_pipelineC
Move a lead to a specific pipeline
Inputs: lead_id (required), pipeline_id (required), status_id.
move_lead_to_statusC
Move a lead to a specific status
Inputs: lead_id (required), status_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools have distinct purposes targeting specific resources (contacts, leads, pipelines, etc.) with clear action differentiation. However, some overlap exists between 'get_lead_analytics' and 'get_pipeline_analytics' which could cause confusion about their specific focus, and 'move_lead_to_pipeline' vs 'move_lead_to_status' might be ambiguous without understanding the CRM's pipeline/status hierarchy.
All tool names follow a consistent verb_noun pattern using snake_case throughout. The verbs are clear and appropriate (create, get, move), and nouns consistently describe the target resources (contact_activities, lead_events, pipeline_analytics, etc.). This makes the tool set highly predictable and readable.
With 22 tools, this is borderline heavy for a CRM server. While it covers many aspects of CRM operations, the count feels slightly excessive as some tools could potentially be consolidated (e.g., multiple analytics/report tools). However, given the comprehensive domain coverage, it's not unreasonable.
The tool set provides excellent coverage for CRM operations including contact management, lead tracking, pipeline analytics, and reporting. Minor gaps exist in update/delete operations (only create and get operations are present for most resources) and task management lacks creation capabilities, but agents can work around these limitations for most workflows.
Maintenance
Related MCP Connectors
List leads, contacts, companies and tasks; create and update leads in Kommo.
Remote MCP for Kommo CRM: leads, contacts, tasks, notes, pipelines, chats, Salesbot. OAuth.
Your own CRM, fully customizable and agent-driven. Start with contacts, companies and a sales pipeli
Agent-native CRM. 25 tools — contacts, deals, sequences, enrichment waterfall, audit log.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables integration with Kommo CRM to manage leads, add notes and tasks, update custom fields, and list pipelines. Supports multi-tenant authentication and includes an approval system for bulk operations.2MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with Bitrix24 CRM for managing contacts, deals, tasks, and leads via a comprehensive set of tools. It supports advanced features like sales team monitoring, performance analytics, and automated CRM searching.-
- FlicenseBqualityDmaintenanceEnables AI assistants to autonomously interact with Kommo CRM, providing tools for managing pipelines, leads, contacts, and custom fields via the Kommo API v4.271-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage GoHighLevel workspaces through natural language, with 508 tools across 18 domains for complete CRM, marketing, and workflow automation.Apache 2.0