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

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

Variable	Required	Description
KOMMO_SUBDOMAIN	yes	Account subdomain
KOMMO_ACCESS_TOKEN	one of	Long-lived Bearer token
KOMMO_CLIENT_ID / SECRET / REFRESH_TOKEN	one of	OAuth refresh trio
KOMMO_TOKEN_FILE	no	Default .kommo_tokens.json
KOMMO_DRIVE_URL	no	Files host (auto-detected)
KOMMO_NORMALIZE_HAL	no	Default true
MCP_TRANSPORT	no	stdio (default) or http
MCP_HOST / MCP_PORT	no	HTTP bind (default 127.0.0.1:3000)
MCP_AUTH_TOKEN	no	Bearer / x-api-key for HTTP

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": "..." }

Agent skill (skills.sh)

Install the companion Cursor skill that teaches agents how to configure and use this MCP:

npx skills add runitsolutions/kommo-mcp --skill kommo-mcp -a cursor -y --copy

Skill source: skills/kommo-mcp/SKILL.md

Docs

• Kommo API reference
• Long-lived token
• OAuth 2.0
• MCP specification
• skills.sh

License

MIT