使用说明

mcp-chatwoot

MCP（模型上下文协议）服务器查特沃特 --通过人工智能工具管理对话、联系人、消息、代理、团队等。

特性

133工具 涵盖Chatwoot的应用程序、公共、平台、企业和帮助中心API
模块化桶：每个API组都使用环境标志进行选择
多账户：所有工具都接受可选 account_id 针对任何帐户
双重运输：STDIO（克劳德桌面，克劳德代码）和HTTP/SSE（远程访问）
Docker就绪：带健康检查的多阶段构建
会话管理：具有自动清理功能的多会话HTTP
安全模式：在应用程序和平台API级别阻止破坏性操作
已测试：Vitest+nock有240个测试

Buckets概述

Bucket	工具	启用标记	身份验证	安全模式
核心	81	永远在线	`CHATWOOT_API_TOKEN`	`MCP_SAFE_MODE` （14封）
公共	12	`MCP_ENABLE_PUBLIC_API=true`	`inbox_identifier`	无
平台	17	`MCP_ENABLE_PLATFORM_API=true`	`CHATWOOT_PLATFORM_API_TOKEN`	`MCP_PLATFORM_SAFE_MODE` （11封）
企业	8	`MCP_ENABLE_ENTERPRISE=true`	`CHATWOOT_API_TOKEN`	`MCP_SAFE_MODE` （3封）
帮助中心	15	`MCP_ENABLE_HELP_CENTER=true`	`CHATWOOT_API_TOKEN`	`MCP_SAFE_MODE` （3封）

核心工具（81-始终启用）

类别	工具
健康	`chatwoot_health`
联系人	`list_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact`, `search_contacts`, `filter_contacts`, `get_contact_conversations`, `merge_contacts`, `get_contactable_inboxes`
联系人标签	`get_contact_labels`, `add_labels_to_contact`
对话	`list_conversations`, `get_conversation`, `create_conversation`, `update_conversation_status`, `assign_conversation`, `add_labels_to_conversation`, `get_conversation_labels`, `set_conversation_priority`, `get_conversation_counts`, `filter_conversations`, `set_conversation_custom_attributes`
消息	`send_message`, `list_messages`, `delete_message`
代理	`list_agents`, `get_agent`
团队	`list_teams`, `get_team`, `get_team_members`, `create_team`, `update_team`, `delete_team`, `add_team_members`, `update_team_members`, `remove_team_members`
收件箱	`list_inboxes`, `get_inbox`, `get_inbox_agent_bot`
收件箱成员	`list_inbox_agents`, `add_inbox_agents`, `update_inbox_agents`, `remove_inbox_agents`
标签	`list_labels`, `create_label`, `update_label`, `delete_label`
罐装回复	`list_canned_responses`, `create_canned_response`, `update_canned_response`, `delete_canned_response`
报告（v2）	`get_account_report`, `get_report_summary`, `get_conversation_statistics`, `get_conversation_metrics`, `get_first_response_time_report`, `get_inbox_label_matrix_report`, `get_outgoing_messages_report`
网络钩子	`list_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook`
自定义属性	`list_custom_attributes`, `get_custom_attribute`, `create_custom_attribute`, `update_custom_attribute`, `delete_custom_attribute`
自动化规则	`list_automation_rules`, `get_automation_rule`, `create_automation_rule`, `update_automation_rule`, `delete_automation_rule`
自定义筛选器	`list_custom_filters`, `get_custom_filter`, `create_custom_filter`, `update_custom_filter`, `delete_custom_filter`
集成	`list_integrations`
简介	`get_profile`

公共API工具（12- `MCP_ENABLE_PUBLIC_API=true`)

使用的小部件/面向客户端的API inbox_identifier + contact_identifier 用于身份验证。

类别	工具
联系人	`public_create_contact`, `public_get_contact`, `public_update_contact`
对话	`public_create_conversation`, `public_list_conversations`, `public_get_conversation`, `public_resolve_conversation`, `public_toggle_typing`, `public_update_last_seen`
消息	`public_create_message`, `public_list_messages`, `public_update_message`

平台API工具（17- `MCP_ENABLE_PLATFORM_API=true`)

超级管理操作。需要单独 CHATWOOT_PLATFORM_API_TOKEN。参见 docs/PLATFORM_SECURITY.md.

类别	工具
账户	`platform_create_account`, `platform_get_account`, `platform_update_account`, `platform_delete_account`
代理机器人	`platform_list_agent_bots`, `platform_create_agent_bot`, `platform_get_agent_bot`, `platform_update_agent_bot`, `platform_delete_agent_bot`
用户	`platform_create_user`, `platform_get_user`, `platform_update_user`, `platform_delete_user`, `platform_get_user_sso_link`
帐户用户	`platform_list_account_users`, `platform_create_account_user`, `platform_delete_account_user`

企业工具（8-- `MCP_ENABLE_ENTERPRISE=true`)

仅限管理员和企业端点。看 docs/ENTERPRIS.md.

类别	工具
审计日志	`enterprise_list_audit_logs`
报告事件	`enterprise_get_account_reporting_events`, `enterprise_get_conversation_reporting_events`
帐户代理机器人	`enterprise_list_agent_bots`, `enterprise_get_agent_bot`, `enterprise_create_agent_bot`, `enterprise_update_agent_bot`, `enterprise_delete_agent_bot`

帮助中心工具（15-- `MCP_ENABLE_HELP_CENTER=true`)

门户、文章和类别的知识库管理。

类别	工具
传送门	`helpcenter_list_portals`, `helpcenter_create_portal`, `helpcenter_get_portal`, `helpcenter_update_portal`, `helpcenter_delete_portal`
条款	`helpcenter_list_articles`, `helpcenter_create_article`, `helpcenter_get_article`, `helpcenter_update_article`, `helpcenter_delete_article`
分类	`helpcenter_list_categories`, `helpcenter_create_category`, `helpcenter_get_category`, `helpcenter_update_category`, `helpcenter_delete_category`

快速开始

选项A:Docker（推荐用于生产环境）

docker run -d \
  -e CHATWOOT_BASE_URL=https://your-chatwoot.com \
  -e CHATWOOT_API_TOKEN=your_token \
  -e MCP_MODE=http \
  -e AUTH_TOKEN=your_secret \
  -p 3000:3000 \
  ghcr.io/renatoascencio/mcp-chatwoot:latest

选项B：本地安装

1.克隆和构建

git clone https://github.com/RenatoAscencio/mcp-chatwoot.git
cd mcp-chatwoot
npm install
npm run build

2.配置

cp .env.example .env
# Edit .env with your Chatwoot credentials:
#   CHATWOOT_BASE_URL=https://your-chatwoot.com
#   CHATWOOT_ACCOUNT_ID=1    (optional — omit to require account_id per tool call)
#   CHATWOOT_API_TOKEN=your_token

在哪里找到您的API代币：在Chatwoot，转到个人资料设置→ 访问令牌。

3.跑步

STDIO模式 （适用于克劳德桌面/Claude代码）：

npm start

HTTP模式 （用于远程访问）：

MCP_MODE=http AUTH_TOKEN=your_secret npm start

Claude桌面配置

增添 ~/.claude/mcp.json:

{
  "mcpServers": {
    "chatwoot": {
      "command": "node",
      "args": ["/path/to/mcp-chatwoot/dist/index.js"],
      "env": {
        "CHATWOOT_BASE_URL": "https://your-chatwoot.com",
        "CHATWOOT_API_TOKEN": "your_api_token"
      }
    }
  }
}

备注: CHATWOOT_ACCOUNT_ID 是可选的。如果省略，则每次工具调用都需要 account_id 作为参数，允许从单个实例使用多个帐户。

启用可选Buckets

{
  "mcpServers": {
    "chatwoot": {
      "command": "node",
      "args": ["/path/to/mcp-chatwoot/dist/index.js"],
      "env": {
        "CHATWOOT_BASE_URL": "https://your-chatwoot.com",
        "CHATWOOT_API_TOKEN": "your_api_token",
        "MCP_ENABLE_PUBLIC_API": "true",
        "MCP_ENABLE_ENTERPRISE": "true",
        "MCP_ENABLE_HELP_CENTER": "true",
        "MCP_ENABLE_PLATFORM_API": "true",
        "CHATWOOT_PLATFORM_API_TOKEN": "your_platform_token",
        "MCP_PLATFORM_SAFE_MODE": "false"
      }
    }
  }
}

环境变量

变量	必填	默认	描述
`CHATWOOT_BASE_URL`	是	--	Chatwoot实例URL
`CHATWOOT_ACCOUNT_ID`	否	--	默认帐户ID（如果省略， `account_id` 每次工具调用都需要）
`CHATWOOT_API_TOKEN`	是	-	应用程序API访问令牌
`MCP_MODE`	没有	`stdio`	运输方式： `stdio` 或 `http`
`PORT`	没有	`3000`	HTTP服务器端口
`AUTH_TOKEN`	没有	--	HTTP模式的承载令牌
`LOG_LEVEL`	没有	`info`	日志级别： `debug`, `info`, `warn`, `error`
`MCP_SAFE_MODE`	没有	`false`	块破坏性应用程序API操作
`MCP_ENABLE_PUBLIC_API`	没有	`false`	启用公用/客户端API工具（12）
`MCP_ENABLE_PLATFORM_API`	没有	`false`	启用平台API工具（17）
`CHATWOOT_PLATFORM_API_TOKEN`	无	-	平台应用程序API令牌（如果平台已启用，则为必需）
`MCP_PLATFORM_SAFE_MODE`	没有	`true`	块平台API写入/删除
`MCP_ENABLE_ENTERPRISE`	没有	`false`	启用企业/利基工具（8）
`MCP_ENABLE_HELP_CENTER`	没有	`false`	启用帮助中心工具（15）

安全

应用程序API安全模式

当 MCP_SAFE_MODE=true，阻止14个破坏性核心工具和6个企业/帮助中心破坏性工具。看 docs/SCOPE.md 查看完整列表。

平台API安全模式

当 MCP_PLATFORM_SAFE_MODE=true （默认），阻止所有11个写入/删除平台API工具。只允许进行读取操作。看 docs/PLATFORM_SECURITY.md 了解详情。

建筑

src/
├── index.ts              # Entry point (STDIO/HTTP mode selection)
├── server.ts             # MCP Server (STDIO transport)
├── http-server.ts        # HTTP/SSE server with session management
├── api/
│   ├── client.ts         # Application API client (81 + Enterprise + Help Center)
│   ├── public-client.ts  # Public/Client API client
│   ├── platform-client.ts # Platform API client
│   └── types.ts          # TypeScript interfaces
├── tools/
│   ├── definitions.ts    # Core tool schemas (81 tools)
│   ├── handlers.ts       # Core tool execution handlers
│   ├── public/           # Public API bucket
│   ├── platform/         # Platform API bucket
│   ├── enterprise/       # Enterprise/Niche bucket
│   └── helpcenter/       # Help Center bucket
└── utils/
    ├── config.ts         # Environment configuration
    └── logger.ts         # Structured logging

发展

# Dev with hot reload
npm run dev

# Dev in HTTP mode
npm run dev:http

# Type check
npm run lint

# Run tests
npm test

# Build
npm run build

多账户支持

所有应用程序API工具都接受 account_id 参数。当 CHATWOOT_ACCOUNT_ID 设置为默认值 account_id 变为可选。当未设置时， account_id 每次工具调用都需要它——这使单个MCP实例能够为多个Chatwoot帐户提供服务。

文档

docs/API_COVERAGE.md文件 -应用程序API覆盖矩阵
docs/SCOPE.md --工具范围和安全模式行为
docs/PLATFORM_SECURITY.md -平台API安全指南
docs/ENTERPRIS.md --企业端点文档
更改日志.md --发布历史

码头工人

预构建的多拱形映像（amd64+arm64）在每次发布时都会发布到GitHub容器注册表中：

docker pull ghcr.io/renatoascencio/mcp-chatwoot:latest
docker run -d \
  -e CHATWOOT_BASE_URL=https://your-chatwoot.com \
  -e CHATWOOT_API_TOKEN=your_token \
  -e MCP_MODE=http \
  -e AUTH_TOKEN=your_secret \
  -p 3000:3000 \
  ghcr.io/renatoascencio/mcp-chatwoot:latest

或使用 docker-compose.yml 以回购为起点。

贡献

欢迎捐款。拜托：

分叉存储库
创建要素分支(git checkout -b feature/my-feature)
运行测试(npm test)并确保它们通过
用描述性消息提交
打开拉取请求

对于较大的更改，请先打开一个问题进行讨论。

Chatwoot模型上下文协议服务器

使用说明

mcp-chatwoot

特性

Buckets概述

核心工具（81-始终启用）

公共API工具（12- `MCP_ENABLE_PUBLIC_API=true`)

平台API工具（17- `MCP_ENABLE_PLATFORM_API=true`)

企业工具（8-- `MCP_ENABLE_ENTERPRISE=true`)

帮助中心工具（15-- `MCP_ENABLE_HELP_CENTER=true`)

快速开始

选项A:Docker（推荐用于生产环境）

选项B：本地安装

1.克隆和构建

2.配置

3.跑步

Claude桌面配置

启用可选Buckets

环境变量

安全

应用程序API安全模式

平台API安全模式

建筑

发展

多账户支持

文档

码头工人

贡献

许可证

使用说明

mcp-chatwoot

特性

Buckets概述

核心工具（81-始终启用）

公共API工具（12- MCP_ENABLE_PUBLIC_API=true)

平台API工具（17- MCP_ENABLE_PLATFORM_API=true)

企业工具（8-- MCP_ENABLE_ENTERPRISE=true)

帮助中心工具（15-- MCP_ENABLE_HELP_CENTER=true)

快速开始

选项A:Docker（推荐用于生产环境）

选项B：本地安装

1.克隆和构建

2.配置

3.跑步

Claude桌面配置

启用可选Buckets

环境变量

安全

应用程序API安全模式

平台API安全模式

建筑

发展

多账户支持

文档

码头工人

贡献

许可证

相关 MCP

ChatGPT交互工具

Loki日志查询服务

Genkit MCP 集成插件

WHOIS查询服务

运行时参数注入工具

AI工具交互框架

公共API工具（12- `MCP_ENABLE_PUBLIC_API=true`)

平台API工具（17- `MCP_ENABLE_PLATFORM_API=true`)

企业工具（8-- `MCP_ENABLE_ENTERPRISE=true`)

帮助中心工具（15-- `MCP_ENABLE_HELP_CENTER=true`)