内容
# kommo-mcp
[](./LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
自托管 [**MCP** (Model Context Protocol)](https://modelcontextprotocol.io) 服务器，用于 [**Kommo CRM**](https://www.kommo.com) （旧名 amoCRM，API v4）。
直接将 **Claude** — 或任何MCP客户端（Claude Code、Claude Desktop、Cursor等）— 连接到您的Kommo账户，使用您的 **长期令牌**。无需中间人：凭证和数据仅在您的机器/服务器和Kommo API之间传输。
有了它，助手可以 **实时操作CRM** （创建/移动线索，编写任务，交换负责人，审核机器人执行的操作）而不是仅仅依赖仪表板和电子表格。
---
## 目录
- [功能](#功能)
- [前提条件](#前提条件)
- [安装](#安装)
- [1. 生成Kommo令牌](#1-生成Kommo令牌)
- [2. 配置`.env`](#2-配置env)
- [3. 测试连接](#3-测试连接)
- [在Claude Code中使用](#在Claude-Code中使用)
- [在其他MCP客户端中使用](#在其他MCP客户端中使用)
- [工具参考](#工具参考)
- [项目结构](#项目结构)
- [安全](#安全)
- [已知限制](#已知限制)
- [故障排除](#故障排除)
- [部署到服务器（VPS）](#部署到服务器VPS)
- [许可证](#许可证)
---
## 功能
**41种工具**，**4种提示**和**8种资源** MCP：
| 类别 | 工具 |
|---|---|
| **读取** | `kommo_account`, `kommo_pipelines`, `kommo_users` （包含`is_active`）， `kommo_custom_fields`, `kommo_search_leads`, `kommo_get_lead`, `kommo_list_tasks`, `kommo_search_contacts`, `kommo_search_companies`, `kommo_list_webhooks`, `kommo_tags`, `kommo_loss_reasons`, `kommo_catalog_elements` |
| **审核** | `kommo_get_events` （翻译后的动态：阶段/作者按名称；`created_by=0` = 机器人/自动化） |
| **服务** | `kommo_talks` （实时对话队列）， `kommo_close_talk`, `kommo_unsorted` （收件箱）， `kommo_unsorted_accept`, `kommo_unsorted_decline` |
| **线索** | `kommo_create_lead`, `kommo_update_lead` （包含标签）， `kommo_change_responsible`, `kommo_bulk_update_leads` （批量处理） |
| **任务和笔记** | `kommo_create_task` （真实类型在描述中）， `kommo_complete_task`, `kommo_add_note` （common/call_in/call_out） |
| **联系人和公司** | `kommo_create_contact`, `kommo_update_contact`, `kommo_create_company`, `kommo_update_company`, `kommo_link` （包含catalog_elements） |
| **渠道/阶段** | `kommo_create_status`, `kommo_update_status` |
| **Webhooks** | `kommo_subscribe_webhook`, `kommo_delete_webhook` |
| **自定义字段** | `kommo_create_custom_field`, `kommo_update_custom_field` （包含`add_enums`） |
| **目录和文件** | `kommo_create_catalog_element`, `kommo_upload_file` |
| **自动化** | `kommo_run_salesbot` （在线索上触发机器人；始终确认） |
| **常规** | `kommo_request` （身份验证的直通，限制在`*.kommo.com`主机） |
**响应格式：** 列表返回 `{ items, page, has_more }`，带有**摘要和可读**的项目（渠道/阶段/负责人按名称，联系人电话，账户时区日期）；`raw: true` 返回原始API负载。所有工具都声明MCP注释（`readOnlyHint`/`destructiveHint`），因此客户端可以根据协议启用读取权限和阻止写入权限。
**提示** （变为MCP客户端命令）：`auditoria-do-dia`, `fila-agora`, `leads-parados`, `relatorio-perdas`。
**资源**： `kommo://account`, `kommo://pipelines`, `kommo://users`, `kommo://custom-fields/{leads,contacts,companies}`, `kommo://loss-reasons`, `kommo://task-types`。
---
## 前提条件
- **Node.js ≥ 18** （使用原生`fetch`；除了MCP SDK外，无需其他运行时依赖）。
- 一个具有 **管理员权限** 的 **Kommo** 账户（用于生成令牌）。
- 一个MCP客户端 — 本README重点介绍 **[Claude Code](https://docs.claude.com/claude-code)**。
---
## 安装
```bash
git clone https://github.com/RonaldoESantosRevOps/kommo-mcp.git
cd kommo-mcp
npm install
```
---
## 1. 生成Kommo令牌
使用 **长期令牌** （不会过期多年，不需要刷新）：
1. 在Kommo中，进入 **设置 → 集成**。
2. 点击创建 **私人集成** （不需要填写Redirect URL或webhook）。
3. 打开 **密钥和范围**选项卡。
4. 点击 **生成长期令牌**，选择有效期（最多5年），**复制令牌**。
5. `crm` **范围** 已经足够使用所有工具。
小心保存令牌 — 它具有与管理员权限相同的访问权限。
> 官方文档： <https://pt-developers.kommo.com/docs/token-de-longa-duracao>
---
## 2. 配置`.env`
复制示例并填写：
```bash
cp .env.example .env
```
```env
KOMMO_SUBDOMAIN=您的子域名 # .kommo.com前面的部分（例如："minhaempresa"）
KOMMO_TOKEN=您的长期令牌
```
`.env` 已在 `.gitignore` 中 — **绝不** 版本控制它。服务器从 `index.mjs` 旁边读取该文件，因此您不需要手动导出环境变量。
---
## 3. 测试连接
```bash
npm run smoke
```
此烟雾测试通过MCP协议启动服务器并调用 **实时API** 的读取工具。
预期输出（摘要）：
```
✓ 暴露的工具：41
✓ annotations ok (16种工具只读)
✓ allowlist阻止外部主机直通
✓ kommo_account -> <您的账户名称> （id ...，BRL）
✓ kommo_pipelines -> N个渠道；主要：...
✓ kommo_users -> N个用户（M个 inactive: ...）
✓ kommo_search_leads -> 摘要ok；...
✓ kommo_get_events -> 5个翻译的事件（作者，阶段按名称，ISO）
✓ kommo_talks / kommo_unsorted / kommo_tags / kommo_loss_reasons ...
✓ SMOKE OK
```
可选的写入测试（`node smoke.mjs --write`）执行无害的Webhook轮询（签名，检查并删除），不会触及线索或联系人。
如果出现 `HTTP 401 Invalid user name or password`，请参阅 [故障排除](#故障排除)。
---
## 在Claude Code中使用
### 注册服务器
```bash
claude mcp add kommo -s user -- node /绝对路径/到/kommo-mcp/index.mjs
```
- 使用 **绝对路径** 到 `index.mjs` （例如：`~/kommo-mcp/index.mjs` 解析为 `/home/you/kommo-mcp/index.mjs`）。
- 服务器从自身读取 `.env`，因此 **不需要** 在命令中传递变量。
**范围** （` -s` ）：
| 范围 | 生效范围 | 何时使用 |
|---|---|---|
| `user` | 您的所有项目 | 推荐 — 您在任何地方使用相同的Kommo账户 |
| `project` | 在存储库中共享（`.mcp.json`） | 如果整个团队将使用 |
| `local` | 仅限您，在此项目 | 临时测试 |
### 验证
```bash
claude mcp get kommo # 应该显示 "Status: ✔ Connected"
claude mcp list # 列出所有MCP服务器
```
> **重启Claude Code** 注册后：MCP服务器的工具仅在会话开始时加载。
### 权限：读取提示，无需确认写入
默认情况下，Claude Code会为每个工具调用请求确认。您可以 **仅限读取工具** （查询）并始终要求 **写入确认**。在您的 `~/.claude/settings.json` 中：
```json
{
"permissions": {
"allow": [
"mcp__kommo__kommo_account",
"mcp__kommo__kommo_pipelines",
"mcp__kommo__kommo_users",
"mcp__kommo__kommo_custom_fields",
"mcp__kommo__kommo_search_leads",
"mcp__kommo__kommo_get_lead",
"mcp__kommo__kommo_list_tasks",
"mcp__kommo__kommo_search_contacts",
"mcp__kommo__kommo_search_companies",
"mcp__kommo__kommo_list_webhooks",
"mcp__kommo__kommo_get_events",
"mcp__kommo__kommo_tags",
"mcp__kommo__kommo_loss_reasons",
"mcp__kommo__kommo_talks",
"mcp__kommo__kommo_unsorted",
"mcp__kommo__kommo_catalog_elements"
]
}
}
```
所有 **写入工具** （创建/编辑线索、联系人、公司、任务、笔记、阶段、自定义字段、链接、Webhook、批量、Inbox accept/decline、Salesbot 和上传） 和 `kommo_request` **继续需要确认** — 推荐的安全行为。 16种读取工具也声明 `readOnlyHint: true`，因此支持annotations的客户端已经将它们视为安全。
### 使用示例（自然语言）
注册后，只需向Claude提出请求：
- *"列出在 'Interesse em Agendar' 的 'Interesse' 渠道中暂停的线索。*"
- *"机器人今天做了什么？请拉取 `created_by=0` 事件，过去6小时内。*"
- *"创建一个线索 'João da Silva'，电话 +55 11 99999-9999，在 'qualificação' 渠道中。*"
- *"将线索 #12345 移至 'Pagamento' 并更改负责人为 Ana。*"
- *"在线索 #12345 中为 Carlos 创建明天 10:00 的跟进。*"
---
## 在其他MCP客户端中使用
服务器通过 **stdio** 使用MCP，因此任何兼容的客户端都可以使用。Claude Desktop、Cursor等通用配置示例：
```json
{
"mcpServers": {
"kommo": {
"command": "node",
"args": ["/绝对路径/到/kommo-mcp/index.mjs"]
}
}
}
```
`.env` 从服务器目录读取，因此不需要通过JSON传递 `env` （但如果需要，可以注入 `KOMMO_SUBDOMAIN`/`KOMMO_TOKEN`）。
---
## 工具参考
> 日期接受ISO（`2026-06-26T10:00`）或纪元时间戳。渠道/阶段/用户ID通过 `kommo_pipelines` 和 `kommo_users` 查询。列表返回 `{ items, page, has_more }`；如果有 `raw`，则 `raw: true` 返回原始API负载。
### 读取
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_account` | - | 账户数据（确认连接）。 |
| `kommo_pipelines` | - | 列出渠道及其阶段（`id`，`name`，`sort`，`type`）。 |
| `kommo_users` | - | 列出用户及其 `is_active`/`is_admin`（不要分配给非活动用户）。 |
| `kommo_custom_fields` | `entity` (`leads`/`contacts`/`companies`) | 列出自定义字段及其 `id`。 |
| `kommo_search_leads` | `query`，`pipeline_id`，`status_id`（自动解析渠道），`responsible_user_id`，`created_from/to`，`updated_from/to`，`order_by`，`fields[]`，`raw`，`limit`，`page` | 搜索摘要线索（渠道/阶段/负责人按名称，电话，标签，损失原因）。 |
| `kommo_get_lead` | `lead_id`*，`note_limit` | 获取线索详情（联系人，目录，损失原因）；如果 `note_limit>0` 则附加笔记。 |
| `kommo_list_tasks` | `responsible_user_id`，`entity_id`，`entity_type`，`is_completed`，`limit`，`page` | 列出任务摘要。 |
| `kommo_search_contacts` | `query`，`raw`，`limit`，`page` | 搜索联系人（提取电话/电子邮件）。 |
| `kommo_search_companies` | `query`，`raw`，`limit`，`page` | 搜索公司。 |
| `kommo_list_webhooks` | - | 列出配置的Webhook（目标和事件）。 |
| `kommo_tags` | `entity`，`query`，`limit`，`page` | 列出标签（ID，名称，颜色）。 |
| `kommo_loss_reasons` | - | 列出配置的损失原因。 |
| `kommo_catalog_elements` | `catalog_id`*，`query`，`limit`，`page` | 列出目录元素（产品/服务）。 |
### 审计
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_get_events` | `entity`，`entity_id`，`type[]`，`created_by[]`，`from`，`to`，`raw`，`limit`，`page` | **翻译** 事件动态（阶段和作者按名称，账户时区日期）。 **`created_by=0` = 机器人/自动化操作。 |
### 服务和Inbox
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_talks` | `is_in_work`，`is_read`，`contact_id`，`limit`，`page` | 实时对话队列。 |
| `kommo_close_talk` | `talk_id`*，`force_close` | 关闭对话。 |
| `kommo_unsorted` | `category`，`pipeline_id`，`summary`，`limit`，`page` | 未分配线索Inbox（`summary: true` = 聚合）。 |
| `kommo_unsorted_accept` | `uid`*，`user_id`，`status_id` | 接受Inbox项目（变为活动线索）。 |
| `kommo_unsorted_decline` | `uid`*，`user_id` | 拒绝Inbox项目（难以撤销）。 |
### 线索写入
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_create_lead` | `name`*，`price`，`pipeline_id`，`status_id`，`responsible_user_id`，`contact_name`，`contact_phone`，`tags[]`，`custom_fields_values` | 创建线索；链接联系人（如果提供）。 |
| `kommo_update_lead` | `lead_id`*，`name`，`price`，`status_id`，`pipeline_id`，`responsible_user_id`，`loss_reason_id`，`tags_to_add[]`，`tags_to_remove[]`，`custom_fields_values` | 更新线索；标签会合并保留现有标签。 |
| `kommo_change_responsible` | `lead_ids[]`*，`responsible_user_id`* | 批量更换负责人（自动分批）。 |
| `kommo_bulk_update_leads` | `lead_ids[]`*，`status_id`，`pipeline_id`，`responsible_user_id`，`price`，`loss_reason_id`，`tags_to_add[]` | 批量更新，200个项目/批次，成功/失败报告。 |
| `kommo_add_note` | `entity_id`*，`text`*，`entity`，`note_type` (`common`/`call_in`/`call_out`)，`params_extra` | 添加笔记或通话记录。 |
| `kommo_create_task` | `text`*，`entity_id`，`entity`，`complete_till`，`responsible_user_id`，`task_type_id`（真实类型在描述中） | 创建任务（默认截止日期：+1天）。 |
| `kommo_complete_task` | `task_id`*，`result` | 完成任务，可选结果。 |
### 联系人和公司
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_create_contact` | `name`/`first_name`/`last_name`，`phone`，`email`，`responsible_user_id`，`custom_fields_values` | 创建联系人（电话/电子邮件成为PHONE/EMAIL字段）。 |
| `kommo_update_contact` | `contact_id`*，`name`，`responsible_user_id`，`custom_fields_values` | 更新联系人。 |
| `kommo_create_company` | `name`*，`responsible_user_id`，`custom_fields_values` | 创建公司。 |
| `kommo_update_company` | `company_id`*，`name`，`responsible_user_id`，`custom_fields_values` | 更新公司。 |
| `kommo_link` | `entity`*，`entity_id`*，`to_entity_type`*（包括`catalog_elements`），`to_entity_id`*，`catalog_id`，`quantity` | 链接实体，包括产品/程序到线索。 |
### 渠道/阶段
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_create_status` | `pipeline_id`*，`name`*，`sort`，`color` | 在渠道中创建阶段。 |
| `kommo_update_status` | `pipeline_id`*，`status_id`*，`name`，`sort`，`color` | 重命名/重新排序/重新着色阶段。 |
### Webhooks
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_subscribe_webhook` | `destination`*（URL），`settings`*（事件） | 在URL上签名事件。 |
| `kommo_delete_webhook` | `destination`* | 通过URL取消Webhook。 |
### 自定义字段
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_create_custom_field` | `entity`，`name`*，`type`，`enums` | 创建自定义字段（使用`enums`进行选择/多选）。 |
| `kommo_update_custom_field` | `entity`，`field_id`*，`name`，`add_enums[]` | 重命名和/或向选择题添加选项。 |
### 目录、文件和自动化
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_create_catalog_element` | `catalog_id`*，`name`*，`custom_fields_values` | 创建目录元素（例如：带价格的程序）。 |
| `kommo_upload_file` | `file_path`*，`file_name`，`entity`，`entity_id` | 上传文件到驱动器并将其附加到实体（如果指定）。 |
| `kommo_run_salesbot` | `bot_id`*，`entity_id`*，`entity_type` | **触发Salesbot在一个线索上（发送真实消息）。始终确认。** |
### 通用
| 工具 | 主要参数 | 功能 |
|---|---|---|
| `kommo_request` | `method`，`path`*，`query`，`body` | 身份验证的直通调用；仅限于账户的 `*.kommo.com` 主机。 |
`*` = 必须
---
## 结构
```
kommo-mcp/
├── index.mjs # MCP服务器：41种工具，4种提示，8种资源，stdio传输
├── kommo.mjs # HTTP客户端（主机允许列表，重试/退避，超时，缓存）+ .env
├── smoke.mjs # 端到端测试：启动服务器并验证实时API
├── package.json
├── .env.example # 变量模型（复制到.env）
├── .gitignore # 忽略.env和node_modules
├── LICENSE
└── README.md
```
---
## 安全
- **主机允许列表**：HTTP客户端仅向 `{您的子域名}.kommo.com` 和 `drive*.kommo.com` 发送令牌。即使有人诱导助手调用 `kommo_request` 到外部URL，令牌也不会离开Kommo基础设施。
- **MCP注释**：读取声明 `readOnlyHint`，写入声明 `destructiveHint`，允许客户端按协议应用不同的权限。
- **绝不** 版本控制 `.env` （已受 `.gitignore` 保护）。要共享配置，请使用 `.env.example`。
- 令牌具有生成者的 **管理员权限** — 请像对待密码一样处理它。
- 如果令牌泄漏，请在Kommo上 **生成另一个**：这立即使前一个令牌失效。
- 创建私人集成时，请使用 **最小范围** (`crm`)。
- 在 **您控制的** 机器/服务器上运行服务器。
---
## 已知限制
- **Kommo原生Salesbot**：Salesbot的**流程/场景** 只能通过Kommo **界面** 编辑。 通过API，可以 **读取Salesbot执行的所有操作** （通过 `kommo_get_events` / 笔记）和 **在一个线索上触发Salesbot** (`kommo_run_salesbot`) — 但 **不能** 重新设计流程。
- **聊天消息（amojo）**：读取/发送对话内容需要注册单独的Chats API凭证（单独凭证）；超出此服务器的范围。
- **客户模块**：仅在具有启用模块的账户中支持（`customers_mode` ≠ `disabled`）；如果适用，可以通过 `kommo_request` 访问。
- **v2.x更改列表格式** 为 `{ items, page, has_more }`，带有摘要项目（v1.x返回原始数组）。在需要原始负载时使用 `raw: true`。
---
## 故障排除
**`HTTP 401 Invalid user name or password`**
令牌被拒绝。常见原因：
- 子域名 (`KOMMO_SUBDOMAIN`) 和令牌来自 **不同的账户**。请在Kommo登录URL中确认子域名（ `.kommo.com` 前面的部分）。
- 私人集成处于 **禁用/草稿** 状态，或者您 **生成了新的令牌** （使其立即失效）。生成新的令牌并更新 `.env`。
- 创建集成的用户不再是 **管理员** 或已被禁用。
**工具在Claude Code中不可见**
请在添加 `claude mcp add` 后重启Claude Code — MCP服务器仅在会话开始时加载。
用 `claude mcp get kommo` 检查。
**缺少KOMMO_SUBDOMAIN和/或KOMMO_TOKEN**
`.env` 未找到或不完整。请确认它存在于项目根目录并包含两个变量。
---
## 部署到服务器（VPS）
由于传输是 **stdio**，服务器在客户端MCP调用时 **按需运行** — 不需要像网络服务一样一直运行。 要在VPS上使用：
```bash
git clone https://github.com/RonaldoESantosRevOps/kommo-mcp.git
cd kommo-mcp && npm install
cp .env.example .env # 填写您的子域名和令牌
```
并在服务器上指向 `index.mjs` 的路径。
---
## 许可证
[MIT](./LICENSE) © Ronaldo E. Santos
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器