Chatwoot MCP服务器
用于Chatwoot API集成的模型上下文协议（MCP）服务器。使AI助手能够管理Chatwoot中的客户对话、消息和联系人。
特性
- 对话管理：列出、筛选和检索对话详细信息
- 消息操作：读取消息历史记录并发送新消息
- 类型安全：使用OpenAPI生成的类型使用TypeScript构建
- 灵活的身份验证：同时支持API令牌（推荐）和JWT身份验证
提供的工具
对话
chatwoot_list_conversations-列出带有筛选功能的对话（状态、受让人、收件箱）chatwoot_get_conversation-获取特定对话的详细信息
消息
chatwoot_list_messages-列出对话中的所有消息chatwoot_create_message-发送消息或创建内部注释
安装
通过npm（推荐）
npx chatwoot-mcp-server或全局安装：
npm install -g chatwoot-mcp-server
chatwoot-mcp-server来源
git clone https://github.com/hugoblanc/chatwoot-mcp.git
cd chatwoot-mcp
npm install
npm run build配置
推荐：API访问令牌
使用Chatwoot API令牌的最简单方法（无过期）。
获取您的API令牌：
- 登录您的Chatwoot帐户
- 点击您的头像→ 配置文件设置
- 滚动到底部→ 复制您的“访问令牌”
配置 .env:
CHATWOOT_BASE_URL="https://your-chatwoot-instance.com"
CHATWOOT_API_TOKEN="your_api_token_here"替代方案：JWT身份验证
如果API令牌在您的实例上不起作用，请使用电子邮件/密码（需要密码才能刷新令牌）。
CHATWOOT_BASE_URL="https://your-chatwoot-instance.com"
CHATWOOT_EMAIL="your@email.com"
CHATWOOT_PASSWORD="your_password"注： JWT令牌过期，需要密码才能自动刷新。
对于自托管实例很重要
如果使用nginx作为反向代理（例如CapRover），请将其添加到nginx配置中以支持API令牌：
server {
...
underscores_in_headers on; # Required for api_access_token header
...
}用法
使用Claude代码
claude mcp add chatwoot \
-e CHATWOOT_BASE_URL="https://your-instance.com" \
-e CHATWOOT_API_TOKEN="your_token" \
-- npx chatwoot-mcp-server与Claude Desktop一起使用
添加 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"chatwoot": {
"command": "npx",
"args": ["chatwoot-mcp-server"],
"env": {
"CHATWOOT_BASE_URL": "https://your-chatwoot-instance.com",
"CHATWOOT_API_TOKEN": "your_api_token"
}
}
}
}开发模式（来源）
npm run dev查询示例
连接后，您可以问Claude以下问题：
- “显示帐户3中所有打开的对话”
- “123号对话的细节是什么？”
- “列出对话#456中的所有消息”
- “向对话#789发送回复，说‘谢谢您联系我们！’”
- “在对话#101中添加一条关于客户问题的内部说明”
测试
运行集成测试：
npm test观看模式：
npm run test:watch项目结构
chatwoot-mcp-server/
├── src/
│ ├── index.ts # Main server entry point
│ ├── constants.ts # Shared constants
│ ├── chatwoot-types.ts # Generated OpenAPI types
│ ├── services/
│ │ ├── chatwoot-client.ts # API client with auth
│ │ ├── chatwoot-auth.ts # JWT authentication
│ │ ├── token-cache.ts # JWT token caching
│ │ └── error-handler.ts # Error handling utilities
│ ├── schemas/
│ │ └── common.ts # Shared Zod schemas
│ └── tools/
│ ├── conversations.ts # Conversation tools
│ └── messages.ts # Message tools
├── test/ # Integration tests
├── swagger.json # Chatwoot OpenAPI spec
└── package.json发展
重新生成类型
如果Chatwoot API发生更改，则重新生成类型：
npm run generate-types添加新工具
- 在中创建新文件
src/tools/ - 定义用于输入验证的Zod模式
- 执行工具功能
- 在中注册该工具
src/index.ts
建筑
npm run build在JavaScript中构建TypeScript dist/ 目录。
故障排除
API代币返回401
如果在nginx中使用自托管实例，请确保 underscores_in_headers on; 在nginx配置中设置。这是必需的，因为 api_access_token 包含下划线。
JWT令牌过期
如果使用JWT身份验证，令牌将过期（通常在2周后）。保持 CHATWOOT_PASSWORD 在 .env 用于自动刷新或切换到API令牌认证。
技术栈
- TypeScript -类型安全开发
- openapi获取 -类型安全的API客户端
- openapi类型脚本 -从OpenAPI规范生成类型
- 黄道带 -运行时输入验证
- @模型上下文协议/sdk -MCP服务器框架
- Vitest -测试框架
许可证
麻省理工学院
贡献
欢迎投稿！可以添加的其他工具：
- 联系人管理（创建、更新、搜索）
- 团队和代理操作
- 收件箱配置
- 标签和自定义属性
- 报告和分析
- 批量操作