Kommo MCP Server

MCP server that exposes the Kommo CRM API v4 (plus Files, Conversations, and analytics helpers) as Model Context Protocol tools, resources, and prompts.

152 tools · resources · prompts · stdio + HTTP · OAuth refresh · rate-limited client

Compared with community servers (Miguelgbastos/Kommo-MCP, ampulex-23/KommoMCP, cAIborg-ai/amocrm-mcp), this project keeps the broadest API surface while adopting their best operational patterns (OAuth persistence, HAL normalization, HTTP deploy, analytics shortcuts).

Features

• Full CRM coverage: leads, contacts, companies, pipelines/stages, tasks, notes, tags, custom fields, catalogs, users/roles, events, links, incoming leads

• Automation & messaging: webhooks, Salesbots, conversations/messages, calls, sources, chat templates, widgets

• Files API: list/get, upload sessions & parts, attach/detach, delete/restore

• Analytics: dashboard, sales report, pipeline analytics (native + aggregation fallback), leads summary

• Convenience tools: kommo_leads_move, kommo_leads_search, date-range filters on lead lists

• Resources: kommo://account, kommo://pipelines, kommo://dashboard, kommo://custom-fields/{entity}

• Prompts: create lead+contact, move lead stage, find contact

• Auth: long-lived token or OAuth refresh with atomic .kommo_tokens.json persistence

• Client: 7 req/s throttle, 429 backoff, 401→refresh retry, HAL normalize ({ data, pagination })

• Transports: stdio (Cursor) and Streamable HTTP (MCP_TRANSPORT=http)

• Ops: Docker, GitHub Actions CI, dotenv, LICENSE

Related MCP server: Kommo CRM MCP Server

Requirements

• Node.js 20+

• Kommo credentials:

  • Private integration long-lived token, or

  • OAuth client_id + client_secret + refresh_token

Setup

npm install
cp .env.example .env
# edit .env
npm run build

Run

npm run dev          # stdio via tsx
npm start            # node dist/index.js (stdio)
MCP_TRANSPORT=http npm start   # http://127.0.0.1:3000/mcp + /health

Docker

docker build -t kommo-mcp .
docker run --rm -p 3000:3000 \
  -e KOMMO_SUBDOMAIN=your-sub \
  -e KOMMO_ACCESS_TOKEN=your-token \
  kommo-mcp

Cursor (stdio)

{
  "mcpServers": {
    "kommo": {
      "command": "node",
      "args": ["/absolute/path/to/kommo-mcp/dist/index.js"],
      "env": {
        "KOMMO_SUBDOMAIN": "your-subdomain",
        "KOMMO_ACCESS_TOKEN": "your-long-lived-token"
      }
    }
  }
}

Tool naming

kommo_<entity>_<action> — e.g. kommo_leads_list, kommo_leads_move, kommo_pipeline_analytics.

Tool responses use envelopes:

{ "data": { "...": "..." }, "pagination": { "page": 1, "has_next": true } }

Errors:

{ "error": "...", "status_code": 401, "detail": "..." }

Docs

• Kommo API reference

• Long-lived token

• OAuth 2.0

• MCP specification

License

MIT