MCP Chatwoot

mcp-chatwoot

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

特性

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

Buckets概述

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

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

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

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

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

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

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

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

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

快速开始

选项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"
      }
    }
  }
}

环境变量

安全

应用程序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 以回购为起点。

贡献

欢迎捐款。拜托：

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

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

许可证