Skip to main content
Glama
Kommo CRM MCP Server

Kommo CRM MCP Server

Kommo MCP Server

English documentation

CI License: MIT Node.js PRs Welcome Contributor Covenant

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-28 pelo SDK oficial, com compatibilidade stateless para clientes da família 2025

  • Dois transportes oficiais: Streamable HTTP para serviços remotos e stdio para clientes locais

  • 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, 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 start

O servidor sobe em http://127.0.0.1:3001/mcp.

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 de ambiente

Variável

Descrição

Default

KOMMO_BASE_URL

URL da conta Kommo (https://<subdominio>.kommo.com)

—

KOMMO_ACCESS_TOKEN

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

—

KOMMO_TIMEOUT_MS

Timeout de cada requisição ao Kommo

15000

KOMMO_MAX_RETRIES

Retentativas de leituras em 429/5xx

3

KOMMO_REQUESTS_PER_SECOND

Limite coordenado de chamadas por processo (máximo 6)

6

KOMMO_TIMEZONE

Fuso IANA dos relatórios; por padrão usa o fuso da conta

conta Kommo

PORT

Porta HTTP do servidor MCP

3001

MCP_HOST

Host de binding

127.0.0.1

MCP_ALLOWED_ORIGINS

Origens permitidas (separadas por vírgula)

—

MCP_AUTH_TOKEN

Protege /mcp; obrigatório quando MCP_HOST não é loopback

—

MCP_RATE_LIMIT_PER_MINUTE

Limite de requisições ao /mcp por endereço e por processo

120

MCP_CONFIRM_WRITES

Exige confirm=true; somente false desativa a proteção

true

LOG_LEVEL

Nível de log

info

Execução

Desenvolvimento:

npm install
npm run dev        # ts-node
# ou
npm run build && npm start

Cliente local via stdio:

npm run build
npm run start:stdio

Docker:

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-server

Em 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 sem MCP_AUTH_TOKEN, inclusive quando createApp() é usado diretamente. A imagem Docker usa 127.0.0.1 por padrão; para publicar a porta, configure conscientemente MCP_HOST=0.0.0.0 junto com um token longo.

A confirmação explícita é obrigatória por padrão nas tools de escrita. Use MCP_CONFIRM_WRITES=false somente em automações controladas que assumam esse risco; o servidor registra um aviso operacional quando essa proteção é desativada. As tools de escrita anunciam destructiveHint; as consultas anunciam readOnlyHint pelo 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 via server/discover

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

  • Readiness: GET http://localhost:3001/ready — verifica se URL e token obrigatórios foram configurados

Ferramentas MCP

Conta e dashboard

Tool

Descrição

get_account

Informações da conta Kommo

get_dashboard

Dashboard calculado com endpoints públicos do Kommo

Leads

Tool

Descrição

get_leads

Listar leads (limit, page, query)

get_lead

Obter lead por ID

create_lead

Criar lead (name, price, status_id, pipeline_id)

update_lead

Atualizar lead existente

move_lead

Mover lead para outro status/pipeline

Pipelines e relatórios

Tool

Descrição

get_pipelines

Listar pipelines (com status opcional por pipeline_id)

get_sales_report

Relatório de vendas (dateFrom, dateTo)

Contatos, empresas e tarefas

Tool

Descrição

get_contacts

Listar contatos

get_companies

Listar empresas

get_tasks

Listar tarefas

create_task

Criar tarefa vinculada a entidade

get_users

Listar usuários da conta

Notas

Tool

Descrição

get_notes

Listar notas de lead/contato/empresa

add_note

Adicionar nota de texto

pin_note

Fixar nota

unpin_note

Desafixar nota

Motivos de perda e Salesbot

Tool

Descrição

get_loss_reasons

Listar motivos da perda de leads

get_loss_reason

Obter motivo de perda por ID

run_salesbot

Iniciar Salesbot (bot_id, entity_id, entity_type=leads)

stop_salesbot

Parar Salesbot (bot_id, entity_id, entity_type=leads)

IA conversacional

Tool

Descrição

ask_kommo

Perguntas em linguagem natural sobre o CRM

Resources

URI

Descrição

kommo://reports/sales

Relatório de vendas (último mês)

kommo://pipelines

Lista de pipelines

kommo://loss_reasons

Motivos da perda de leads

kommo://dashboard

Dados do dashboard

kommo://account

Informações da conta

Prompts

Nome

Descrição

analisar_vendas_mes

Analisar vendas do mês

resumo_leads_status

Resumo de leads por status

analise_pipeline

Analisar performance de pipeline

motivos_perda

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 MCP

Exemplos 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 Unauthorized da API do Kommo — verifique se KOMMO_ACCESS_TOKEN está válido e se KOMMO_BASE_URL aponta para o subdomínio correto da sua conta.

  • Cliente MCP não conecta — confirme se MCP_HOST permite conexões do cliente (0.0.0.0 para acesso remoto) e se MCP_ALLOWED_ORIGINS inclui a origem do cliente, quando definido.

  • 403 no /mcp — se MCP_AUTH_TOKEN estiver definido, é preciso enviar Authorization: Bearer <token> ou X-API-Key: <token>.

  • 503 no /ready — configure KOMMO_BASE_URL com HTTPS e defina KOMMO_ACCESS_TOKEN antes de iniciar o serviço real.

  • 429 do Kommo — todas as chamadas compartilham um limitador coordenado; leituras usam backoff e Retry-After, enquanto escritas não são repetidas automaticamente para evitar duplicidade.

  • 429 do /mcp — o servidor limita cada endereço cliente a 120 requisições por minuto por processo; ajuste MCP_RATE_LIMIT_PER_MINUTE se necessário. O endereço do proxy é usado por padrão, pois trust proxy não é habilitado automaticamente.

  • Docker HEALTHCHECK falha — a imagem usa node --eval para o healthcheck, verifique se a porta interna corresponde a PORT.

  • Erros de build TypeScript — rode npm run typecheck para ver mensagens detalhadas. Requer Node.js 22.13+.

Documentação

Compatibilidade e suporte

Componente

Suporte atual

Node.js

22.13+; CI em Node 22 e 24

Protocolo MCP

2026-07-28 e família 2025 stateless

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:check e npm run audit:prod antes 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 tools
create_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

    B3.2/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to autonomously interact with Kommo CRM, providing tools for managing pipelines, leads, contacts, and custom fields via the Kommo API v4.
      27
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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