AI导哈

Chatwoot MCP 服务器

一个完整的模型上下文协议服务器，将Chatwoot应用API封装为51个MCP工具，支持通过自然语言管理客户对话、联系人、代理等。

  • by drmoyassine
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 drmoyassine/chatwoot-mcp

使用说明

Chatwoot MCP服务器

完整的 模型上下文协议 包装服务器 全部 Chatwoot应用程序API集成到51个MCP工具中。将其连接到n8n、Claude Desktop、Cursor或任何兼容MCP的客户端，通过自然语言管理客户对话、联系人、代理等。

包括内置 仪表板用户界面 用于配置、工具探索和实时测试。

特性

  • 51个MCP工具 覆盖每个Chatwoot应用程序API端点
  • 双重运输 --SSE（HTTP，适用于n8n/远程客户端）和stdio（适用于本地CLI/Claude Desktop）
  • 仪表板用户界面 --配置凭据，浏览所有工具，并从浏览器进行实时测试
  • 对话筛选器生成器 --具有AND/OR逻辑的高级多条件滤波
  • 文件附件 --通过URL或直接上传在消息中发送文件
  • Webhook事件流 --通过SSE实时接收Chatwoot事件
  • Docker就绪 --单身 docker compose up 部署（API+UI+MongoDB）

快速开始

1.克隆和配置

cp .env.example .env

编辑 .env 使用您的Chatwoot证书：

CHATWOOT_URL=https://app.chatwoot.com
CHATWOOT_API_TOKEN=your_access_token
CHATWOOT_ACCOUNT_ID=1

2.使用Docker Compose运行

docker compose up --build -d

这将开始：

  • MCP服务器+仪表板用户界面 上 http://localhost:8001
  • MongoDB 端口27017

打开 http://localhost:8001 在浏览器中访问仪表板。

3.不使用Docker运行

# Backend
cd backend
pip install -r requirements.docker.txt
cp ../.env.example .env   # then edit with your credentials
uvicorn server:app --host 0.0.0.0 --port 8001

# Frontend (separate terminal, for development)
cd frontend
yarn install
REACT_APP_BACKEND_URL=http://localhost:8001 yarn start

访问仪表板UI

部署 URL
Docker编写 http://localhost:8001
没有Docker（开发） http://localhost:3000 （React开发服务器）

仪表板有三个选项卡：

  • 工具 --按类别浏览所有51个MCP工具，搜索、选择并使用实时测试终端执行
  • 过滤器 --可视化对话过滤器构建器，带有属性/运算符/值下拉菜单和and/OR逻辑
  • 网络钩子 --实时馈送传入的Chatwoot webhook事件

MCP工具参考

账户（2）

工具 说明
get_account 获取帐户详细信息（名称、区域设置、功能、设置）
update_account 更新帐户名或区域设置

代理商（4）

工具 说明
list_agents 列出所有代理（ID、姓名、电子邮件、角色、可用性）
add_agent 添加新代理（姓名、电子邮件、角色）
update_agent 更新代理名称、角色或可用性
remove_agent 按ID删除代理

联系人（7）

工具 说明
list_contacts 使用分页和排序功能列出联系人
create_contact 创建联系人（姓名、电子邮件、电话、标识符）
get_contact 按ID获取联系方式
update_contact 更新联系人姓名、电子邮件或电话
delete_contact 删除联系人
search_contacts 按姓名、电子邮件、电话或标识符搜索
get_contact_conversations 获取联系人的所有对话

对话（9）

工具 说明
list_conversations 带筛选器的列表（受让人、状态、收件箱、团队、搜索）
create_conversation 创建新对话（收件箱、联系人、受让人、消息）
get_conversation 按ID获取对话详细信息
get_conversation_counts 按状态和受让人类型获取计数
toggle_conversation_status 设置状态：打开、已解决、待定、已暂停
assign_conversation 分配给代理人和/或团队
get_conversation_labels 为对话添加标签
add_conversation_labels 为对话设置标签
filter_conversations_advanced 多条件过滤器（状态、受让人、收件箱、优先级等）

留言（4）

工具 说明
get_messages 在对话中获取消息（带分页）
create_message 发送短信（传出/传入、私人备忘）
delete_message 删除邮件及其附件
create_message_with_attachment 通过URL发送带有文件附件的消息

收件箱（4）

工具 说明
list_inboxes 列出所有包含频道详细信息的收件箱
get_inbox 按ID获取收件箱详细信息
create_inbox 创建收件箱（web_widget、api等）
update_inbox 更新收件箱名称或自动分配

团队（5）

工具 说明
list_teams 列出所有团队
create_team 创建团队（名称、描述）
get_team 获取团队详细信息
update_team 更新团队名称或描述
delete_team 删除团队

标签（4）

工具 说明
list_labels 列出所有标签
create_label 创建标签（标题、颜色、侧边栏可见性）
update_label 更新标签标题、描述或颜色
delete_label 删除标签

罐装回复（4）

工具 说明
list_canned_responses 列出预先编写的消息模板
create_canned_response 创建模板（短代码+内容）
update_canned_response 更新模板短代码或内容
delete_canned_response 删除模板

自定义属性（2）

工具 说明
list_custom_attributes 列出属性定义（对话或联系人）
create_custom_attribute 创建属性（文本、数字、日期、列表等）

挂钩（5）

工具 说明
list_webhooks 列出已配置的Webhook
create_webhook 创建webhook（URL+事件订阅）
update_webhook 更新webhook URL或订阅
delete_webhook 删除webhook
setup_webhook_listener 快速设置：注册webhook以获取实时事件

报告（1）

工具 说明
get_account_reports 获取分析（帐户、代理、收件箱、标签、团队）

连接到n8n

  1. 在n8n中，添加一个 MCP客户端 节点
  2. 将SSE URL设置为：
    http://<your-server>:8001/api/mcp/sse
  3. 该节点将自动发现所有51个工具

连接到克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "chatwoot": {
      "command": "python",
      "args": ["mcp_stdio.py"],
      "cwd": "/path/to/backend",
      "env": {
        "CHATWOOT_URL": "https://app.chatwoot.com",
        "CHATWOOT_API_TOKEN": "your_token",
        "CHATWOOT_ACCOUNT_ID": "1"
      }
    }
  }
}

或者使用SSE传输：

{
  "mcpServers": {
    "chatwoot": {
      "url": "http://localhost:8001/api/mcp/sse"
    }
  }
}

Webhook事件

要接收实时Chatwoot事件：

  1. 在Chatwoot注册webhook（或使用 setup_webhook_listener 工具）指向：
    http://<your-server>:8001/api/webhooks/receive
  2. 事件存储在MongoDB中（最近500个），并通过SSE在以下位置进行流式传输：
    GET /api/webhooks/events
  3. 查看事件历史记录：
    GET /api/webhooks/events/history?limit=50

API终点

方法 路径 描述
GET /api/config 获取当前配置
POST /api/config 保存Chatwoot配置
POST /api/config/test 测试Chatwoot连接
GET /api/tools 列出所有51个MCP工具及其元数据
POST /api/tools/execute 执行工具 { tool_name, parameters }
POST /api/tools/execute-with-file 文件上传执行工具（多部分）
GET /api/mcp/info MCP服务器状态和传输信息
GET /api/mcp/sse MCP SSE传输端点
POST /api/webhooks/receive Chatwoot webhook接收器
GET /api/webhooks/events webhook事件的SSE流
GET /api/webhooks/events/history 数据库中最近发生的webhook事件

环境变量

变量 必填 描述
CHATWOOT_URL 是 Chatwoot实例URL（例如。 https://app.chatwoot.com)
CHATWOOT_API_TOKEN 是 来自Chatwoot的API访问令牌
CHATWOOT_ACCOUNT_ID 是 数字帐户ID
MONGO_URL 是 MongoDB连接字符串
DB_NAME 否 数据库名称（默认值： chatwoot_mcp)
CORS_ORIGINS 否 允许的CORS源（默认值： *)

项目结构

├── Dockerfile                        # Multi-stage build (Node + Python)
├── docker-compose.yml                # Docker Compose with MongoDB
├── .dockerignore                     # Docker build exclusions
├── .env.example                      # Environment variable template
├── backend/
│   ├── server.py                     # FastAPI app + REST API + MCP SSE + static file serving
│   ├── mcp_tools.py                  # 51 MCP tool definitions
│   ├── mcp_stdio.py                  # Standalone stdio transport entry point
│   ├── chatwoot_client.py            # Async HTTP client for Chatwoot APIs
│   ├── requirements.docker.txt       # Python dependencies (Docker)
│   └── .env                          # Local environment variables
└── frontend/
    ├── package.json                  # React dependencies
    └── src/
        ├── App.js                    # Main app with tab routing
        └── components/
            ├── Sidebar.js            # Config panel + MCP status + navigation
            ├── ToolExplorer.js       # Tool browser with categories and search
            ├── TestTerminal.js       # Live testing terminal (dark theme)
            ├── FilterBuilder.js      # Visual conversation filter builder
            └── WebhookEvents.js      # Real-time webhook event feed

许可证

麻省理工学院

相关 MCP