rocketchat-mcp

rocketchat-mcp

适用于 Rocket.Chat 的 MCP 服务。 它允许 MCP 客户端（Claude Desktop、Cursor、Claude Code 等）通过 stdio 在 Rocket.Chat 工作区中发送和读取 消息、发送私信、搜索历史记录、上传/下载文件以及管理频道。

积极维护的分支，源自 elieworkspace/rocketchat-mcp， 新增了 Personal Access Token 身份验证、更多工具，以及可靠性和安全性方面的改进。归属信息请参阅 NOTICE。

工具

工具	描述
send_message_in_channel	向频道发送消息
send_direct_message	向用户发送私信
delete_message	删除消息（只能删除自己的消息，除非角色拥有强制删除权限）
get_channel_messages	读取频道/群组/私信的历史记录；支持 offset 分页，并接受房间 ID 或名称
search_messages	在房间中搜索关键词（chat.search）
get_unread	列出有未读消息的房间及其最新内容
send_file	向频道或 @user 上传文件
download_attachment	将消息附件下载到本地文件
list_all_rooms	列出频道、群组和私信 ∗
list_users	列出用户 ∗
get_user_info	获取用户资料
create_channel	创建频道

引用消息和附件

消息列表会包含引用中的文本和已上传文件。引用是包含该引用的消息中保存的快照；原始房间可能已无法访问。 下载引用的附件时，请使用包含该引用的消息 ID。无需先读取原始房间。

download_attachment(message_id, attachment_id) 会下载列表中显示的指定文件 ID。省略 attachment_id 时， 会保留现有行为，下载所有受支持的附件，现在也包括引用的文件。服务仍会强制执行文件访问权限。文件引用必须来自此 Rocket.Chat 服务的 上传路径；重定向到文件存储时，不会携带 Rocket.Chat 身份验证标头。 下载使用唯一的临时文件名，不会覆盖之前下载的文件。

如果可用，HTTP 错误会包含服务器返回的错误类型和消息，因此消息不存在、访问失败和网络故障不会被归为同一种诊断结果。 这些错误摘要不会包含已配置的身份验证密钥。

∗ list_all_rooms 和 list_users 会调用工作区范围的端点 （channels.list / users.list），这些端点需要管理员权限或相应的 view-* 权限。其他所有工具均可供普通聊天用户使用。

身份验证

核心工具只需普通聊天用户权限。建议使用 Personal Access Token —— 这样可以避免将令牌暴露在进程参数中：

变量	描述
ROCKETCHAT_SERVER_URL	工作区 URL，例如 https://chat.example.com
ROCKETCHAT_USER_ID	你的 Rocket.Chat 用户 ID
ROCKETCHAT_AUTH_TOKEN	Personal Access Token
ROCKETCHAT_WATCHDOG_INTERVAL	（可选）孤儿监控间隔，单位为秒，默认为 60

也支持使用用户名/密码，通过 --username / --password 设置。 对于自签名证书，请使用 --no-verify-ssl。

用法

使用 uvx 运行

uvx rocketchat-mcp --server-url https://chat.example.com

若要直接从 GitHub 运行最新的未发布代码：

uvx --from git+https://github.com/millerchou/rocketchat-mcp rocketchat-mcp --server-url https://chat.example.com

客户端配置

{
  "mcpServers": {
    "rocketchat": {
      "command": "uvx",
      "args": ["rocketchat-mcp"],
      "env": {
        "ROCKETCHAT_SERVER_URL": "https://chat.example.com",
        "ROCKETCHAT_USER_ID": "your_user_id",
        "ROCKETCHAT_AUTH_TOKEN": "your_personal_access_token"
      }
    }
  }
}

本地开发

git clone https://github.com/millerchou/rocketchat-mcp
cd rocketchat-mcp
uv run rocketchat.py --server-url https://chat.example.com \
  --auth-token "$ROCKETCHAT_AUTH_TOKEN" --user-id "$ROCKETCHAT_USER_ID"

可靠性

运行离线附件和 API 错误测试：

uv run python -m unittest discover -s tests -v

测试使用合成消息和 HTTP 模拟传输；无需聊天账户。

持久 HTTP 连接池、房间端点缓存、日志轮转（1 MB）， 以及在 MCP 客户端进程退出时自动退出的孤儿监控程序。

许可证

此分支中的修改基于 MIT License 发布。 此分支基于最初发布时未附带许可证的上游代码；详情请参阅 NOTICE。