home / mcp / kommo mcp server

Kommo MCP Server

Provides a multi-tenant MCP server connecting Kommo via HTTP with JSON-RPC 2.0, including validation, caching, and type-safe tooling.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "cardosolucass96-kommo-mcp-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "MCP_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

You can use this multi-tenant MCP server to connect Kommo with a JSON-RPC 2.0 API over HTTP. It validates inputs, caches key data, and provides a secure, type-safe way to perform actions across multiple Kommo accounts from a single service.

How to use

Connect your MCP client to the HTTP endpoint exposed by the server to perform actions against Kommo data. You will authenticate once per session using a Bearer token that includes your MCP password, subdomain, and Kommo access token. Use the supported tools to list leads, update leads, add notes, create tasks, and fetch pipelines or custom fields. The server handles validation, error reporting, and approval flow for multi-record operations.

How to install

Prerequisites: you need a modern Node.js runtime and a running MCP server instance. Install dependencies, build, and start the server using the following steps.

# Install dependencies
npm install

# Build the project
npm run build

# Start in development mode (server + inspector)
npm run dev

# Start in production (build first, then run)
npm run build
npm start

Additional configuration and security

Create a .env file at the project root and set the required password for MCP access. The server will not start without a password. Do not commit real credentials to version control.

Environment variable to configure securely: MCP_PASSWORD. Use a strong, unique value for production.

Notes on usage and behavior

The server enforces input validation through strict schemas, uses a structured JSON-RPC error system, and includes a built-in logging mechanism via Fastify. It also caches frequently retrieved data such as pipelines, stages, and custom fields to optimize performance.

Troubleshooting tips

If the server fails to start, verify that MCP_PASSWORD is set in the environment and that your environment has network access to required endpoints. Check log output for authentication or validation errors and ensure you are using a valid Bearer token format as shown in the usage examples.

Security and best practices

Always use a strong, non-default password for MCP_PASSWORD. Validate all inputs using the provided schemas before issuing requests. Treat tokens with care and rotate credentials regularly. Enable logging to monitor failed attempts and anomalous activity.

Available tools

kommo_list_leads

Lists or searches leads with validation against a Zod schema to ensure correct parameters and types.

kommo_update_lead

Updates a lead's fields such as name, price, status, and custom fields with input validated by a Zod schema.

kommo_add_notes

Adds notes to a lead, with parameters validated by a Zod schema.

kommo_add_tasks

Creates tasks or reminders related to a lead, with strict parameter validation.

kommo_list_pipelines

Lists pipelines and their stages, with pipeline data cached for performance.

kommo_list_pipeline_stages

Lists stages of a specific pipeline, validated by a Zod schema.

kommo_list_lead_custom_fields

Lists custom fields for leads, with cached data.