# 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](https://github.com/Miguelgbastos/Kommo-MCP), [ampulex-23/KommoMCP](https://github.com/ampulex-23/KommoMCP), [cAIborg-ai/amocrm-mcp](https://github.com/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

```bash
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

```bash
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

```bash
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)

```json
{
  "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:

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

Errors:

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

## Agent skill (skills.sh)

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

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

Skill source: [`skills/kommo-mcp/SKILL.md`](skills/kommo-mcp/SKILL.md)

## Docs

- [Kommo API reference](https://developers.kommo.com/reference)
- [Long-lived token](https://developers.kommo.com/docs/long-lived-token)
- [OAuth 2.0](https://developers.kommo.com/docs/oauth-20)
- [MCP specification](https://modelcontextprotocol.io)
- [skills.sh](https://skills.sh/)

## License

MIT