io.github.millerchou/rocketchat-mcp

rocketchat-mcp

An MCP server for Rocket.Chat. It lets MCP clients (Claude Desktop, Cursor, Claude Code, etc.) send and read messages, send DMs, search history, upload/download files, and manage channels on a Rocket.Chat workspace over stdio.

Actively maintained fork of elieworkspace/rocketchat-mcp, adding Personal Access Token auth, more tools, and reliability/security improvements. See NOTICE for attribution.

Tools

Quoted messages and attachments

Message listings include quoted text and uploaded files inside quotes. A quote is a snapshot shared in the containing message; the original room may no longer be accessible. Use the containing message ID when downloading a quoted attachment. You do not need to read the original room first.

download_attachment(message_id, attachment_id) downloads the selected file ID shown in the listing. Omitting attachment_id retains the existing behavior of downloading all supported attachments, now including quoted files. The server still enforces file access permissions. File references must originate from this Rocket.Chat server's upload path; redirects to file storage do not receive Rocket.Chat authentication headers. Downloads use unique temporary filenames and do not overwrite prior downloads.

HTTP errors include the server's error type and message when available, so a missing message, an access failure, and a network failure are not reduced to the same diagnosis. Configured authentication secrets are excluded from these error summaries.

∗ list_all_rooms and list_users call workspace-wide endpoints (channels.list / users.list) that require admin or the corresponding view-* permission. Every other tool works for a normal chat user.

Authentication

A normal chat user is enough for the core tools. A Personal Access Token is recommended — it keeps the token out of process arguments:

Username/password is also supported via --username / --password. Use --no-verify-ssl for self-signed certificates.

Usage

Run with uvx

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

To run the latest unreleased code straight from GitHub instead:

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

Client configuration

{
  "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"
      }
    }
  }
}

Local development

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"

Reliability

Run the offline attachment and API error tests with:

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

The tests use synthetic messages and an HTTP mock transport; no chat account is needed.

Persistent HTTP connection pool, room-endpoint caching, log rotation (1 MB), and an orphan watchdog that self-exits when the MCP client process dies.

License

Modifications in this fork are released under the MIT License. This is a fork of upstream code originally published without a license; see NOTICE for details.