Rocket.Chat E2EE MCP server
Commit Nov 12, 2026Allows an AI client to browse and search Rocket.Chat workspaces, including end-to-end encrypted rooms, by decrypting messages locally.
Also known as alien2003/rocketchat-e2ee-mcp
- Stars
- 0
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- MIT
What is Rocket.Chat E2EE MCP?
Rocket.Chat E2EE allows an AI client to browse and search Rocket.Chat workspaces, including end-to-end encrypted rooms, by decrypting messages locally. It exposes 12 tools, such as list_rooms, get_messages, get_thread.
Summary generated from the project's README
About Rocket.Chat E2EE MCP server
Searching through Rocket.Chat workspaces and private discussions is what this MCP server enables for developers using Claude Code. It provides a read-only interface to browse rooms, follow threads, and search for messages or files. Unlike standard server-side search tools, this server performs decryption locally on your machine using your personal access token and E2EE password. This allows an AI client to access end-to-end encrypted rooms and direct messages that are otherwise invisible to the server.
The server maintains a local SQLite full-text index to ensure fast searching across your history. It functions as a local bridge, fetching ciphertext from your Rocket.Chat instance and transforming it into plaintext for your LLM provider. Users can choose an ephemeral mode to keep the index in memory rather than on disk. Because it is read-only, the tools cannot send messages, react to posts, or modify any workspace data, ensuring your interactions remain strictly observational.
What you can do with it
- 1Retrieve technical documentation from chatAsk the AI to find specific how-to guides or runbooks buried in historical chat threads.
- 2Search encrypted private discussionsLocate information within end-to-end encrypted groups that standard server-side search cannot reach.
- 3Access workspace files via AIRequest the AI to retrieve and read the content of files shared within a Rocket.Chat room.
Written from the project's README. Every use case is checked against a quote from it.
Rocket.Chat E2EE MCP tools 12
Detected from the READMElist_roomsget_messagesget_threadget_messagesearchsyncget_fileget_userroom-notrocketchate2eeinternal
Configuration
RC_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablealien2003/rocketchat-e2ee-mcp is public and reachablegithub.com/alien2003/rocketchat-e2ee-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/alien2003/rocketchat-e2ee-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubrocketchat-e2ee-mcp
A read-only MCP server and CLI (rc-mcp) that lets Claude Code browse and
search a Rocket.Chat workspace, including end-to-end encrypted (E2EE) rooms. It decrypts on your machine with
your own keys (personal access token + E2EE password), the same way the official web client does, keeps a local
full-text index, and exposes rooms, threads, messages and files as MCP tools. It cannot send, edit, react, mark as
read or accept keys.
Contents: Why · How it works · Security model · Limitations · Quickstart · Tools · CLI · Configuration · Troubleshooting · Development · License
Why
Teams keep how-tos, decisions and runbooks in chat threads instead of a wiki. Finding them later means scrolling and guessing search terms. Many of the useful ones live in E2EE private groups and DMs, where the server only stores ciphertext. Server-side tools therefore can't read them. That includes server-side search and Rocket.Chat's own MCP endpoint, which ships with 8.9 as part of the enterprise AI add-on and runs on the server.
rc-mcp runs as you, on your machine. It reads the rooms you can already read, decrypts them locally, and lets
Claude search them, follow threads and quote them back to you with permalinks.
How it works
Key chain
The derivation is a port of the 8.9.0 web client (apps/meteor/client/lib/e2ee) to WebCrypto. Every step is
checked against data produced by the real client.
RC_E2EE_PASSWORD your E2EE password / generated passphrase, taken as Latin-1 bytes like the client does
│
│ PBKDF2-HMAC-SHA256 → 256-bit key
│ stored key v2: salt "v2:<userId>:<uuid>", 100 000 iterations → AES-GCM
│ stored key v1: salt "<userId>", 1 000 iterations → AES-CBC (legacy)
▼
AES master key ──decrypts──▶ your stored private key (e2e.fetchMyKeys → private_key)
▼
RSA-OAEP-2048 private key (JWK, kept in memory only)
│
│ RSA-OAEP-SHA256 unwraps, per room (from subscriptions.get):
│ E2EKey current room key
│ oldRoomKeys[] previous keys after room key resets (the server keeps at most 10)
│ E2ESuggestedKey key offered by another member: used in memory, never accepted
│ (with its suggestedOldRoomKeys[] when you have no oldRoomKeys)
▼
room keys A256GCM (legacy A128CBC), picked per message by key id:
│ the oldRoomKeys entry whose e2eKeyId matches, else the current key
│
│ rc.v2.aes-sha2 AES-GCM-256 rc.v1.aes-sha2 / bare `msg` AES-CBC-128 (legacy)
▼
message content EJSON { msg, attachments, file, files }
│
│ file messages carry a per-file AES-CTR-256 key, a 16-byte counter block
│ and the SHA-256 of the plaintext inside the encrypted content
▼
attachment bytes downloaded ciphertext → AES-CTR → SHA-256 verified
Data flow
Rocket.Chat server (stores only ciphertext for E2EE rooms)
│ HTTPS GET to an allowlist of endpoints, PAT in X-User-Id / X-Auth-Token headers
▼
rc-api zod-validated responses, honours 429 / X-RateLimit-*, serialised per route
▼
e2ee decrypts with your keys in memory; failures become `undecryptable` + reason
▼
index node:sqlite + FTS5: plaintext, search index, sync cursors
│ <dataDir>/index.sqlite (0600), or RAM with RC_MCP_EPHEMERAL=1
▼
MCP tools over stdio · rc-mcp CLI
▼
Claude Code ──▶ LLM provider (receives whatever the tools return)
- Rooms and keys: one
subscriptions.getplus onerooms.get. - Backfill:
rooms.history, 100 messages per page, newest first. - Incremental:
chat.syncMessagesreturns new, edited and deleted messages, one call per changed room. Rooms whose last update did not move are skipped. Rocket.Chat purges its deletion log after 30 days, so a room whose cursor is older than 29 days gets a full resync. - Freshness: there is no websocket and no background polling. Data syncs when a tool needs it:
get_messagesandget_threadrefresh a room whose last sync is older than 60 s.get_messagesreturns only history that the index holds without gaps; paging back withbeforebackfills older messages as needed.searchwithroomsrefreshes those rooms the same way. Withoutrooms, it syncs changed rooms at most every 5 minutes.refresh: falseskips all network work (no sync, and no server search unlessinclude_server_search: trueis passed explicitly).
- Missing keys: messages that can't be decrypted yet are kept as ciphertext. Once the room's keys change (for example after a member shares the key), the next sync of that room decrypts them again locally, without extra REST calls.
- Cold index: when the index lacks a message or a thread's replies,
get_messageandget_threadfetch them live (chat.getMessage,chat.getThreadMessages).get_filealways downloads the file and re-derives its key, from the re-fetched message or, when no message is known, from the room's upload record, because per-file keys are never stored. - Server search: for unencrypted rooms,
searchalso queries Rocket.Chat'schat.searchwhen you passrooms(up to 10 of the named rooms), or, withinclude_server_search: true, for the 10 most recently active unencrypted rooms. It waits at most 2 s for a rate limit; otherwise it skips the server search and says so innotes. - Offline: when Rocket.Chat can't be reached (network error, timeout, HTTP 5xx, 401 or 429) and the index
already has data,
list_rooms,get_messages,get_thread,get_message(for indexed messages) andsearchanswer from the index and add anotesentry saying the results may be stale. After such a failure they skip their network work for 30 s.
Design: docs/architecture.md, the decision records starting at ADR 0001, and the crypto formats in docs/e2ee-protocol.md.
Security model
[!IMPORTANT] Rocket.Chat E2EE guarantees that only room members' devices see plaintext.
rc-mcpadds two places where plaintext ends up: a file on your disk and your LLM provider. Read this section before you point it at a real workspace.
Decrypted text goes to your LLM provider. Every message, thread or file a tool returns becomes part of the conversation. It is sent to the model provider your MCP client uses, and it sits in anything that client stores itself. That widens the E2EE trust boundary for every participant of every room you read, and those people did not opt in. Get the consent of the people in those rooms, follow your organisation's policy on confidential data and AI tools, and leave out rooms where that isn't settled. Don't use it on rooms whose members expect their messages to stay on their devices.
The local index stores plaintext. It is needed for fast full-text search across rooms.
- It lives in
<dataDir>/index.sqlite, with SQLite's-waland-shmfiles next to it. The directory is mode 0700 and is tightened if it is wider. The files are 0600, and the process runs withumask 077, so new files are private to you too. - The data directory must be an absolute path (a leading
~is expanded). A relative path is rejected, so the index can't end up in whatever directory your MCP client started the server in. - Mitigations:
RC_MCP_EPHEMERAL=1keeps the index in memory, andget_filethen writes nothing to disk.rc-mcp purgedeletes the index and saved files. It also works whileRC_MCP_EPHEMERALis set, to remove what earlier non-ephemeral runs left behind.rc-mcp doctorwarns if the index file has become group- or world-readable.- Full-disk encryption is recommended.
get_filereturns text withinmax_inline_bytesand images up to 4 MiB inline, without writing them. Other files:- normal mode: saved (0600) to
<dataDir>/files/(0700), and the path is returned;rc-mcp purgeremoves them; - ephemeral mode: returned inline as an MCP embedded resource (up to 10 MiB), never written to disk.
- normal mode: saved (0600) to
rc-mcp exportwrites plaintext Markdown to stdout, or with-oto a file that it sets to mode 0600, also when the file already existed.
Never stored:
- your E2EE password;
- your private key, in either decrypted or stored form;
- room keys;
- per-file keys:
get_filefetches and decrypts the message again each time; - your access token.
Attachment metadata in the index has its key material stripped. For messages that couldn't be decrypted yet, the index keeps the original ciphertext so they can be retried later.
You only get what you can already read.
rc-mcpuses your PAT and your keys and sees only rooms your account belongs to.- An encrypted room is readable only if your account holds its key, or was offered one (a suggested key).
Suggested keys get the same trust as in the official client, which accepts any suggested key that decrypts with
your private key.
rc-mcpuses them in memory and never accepts them on the server. - It can't read content from before you had the key, or content encrypted with a key older than the 10 the server keeps.
Read-only by construction.
- The REST client has no generic request method. It only issues
GETs to a fixed allowlist of endpoints, plus authenticated downloads under/file-upload/. - It avoids endpoints that change state even on
GET:GET /api/v1/logoutrevokes the calling token, PATs included;chat.ignoreUserchanges your subscription;im.history/im.messagescalled with a username can create a DM;e2e.acceptSuggestedGroupKeywould accept a key on the server.
- Every tool is annotated
readOnlyHint: true,destructiveHint: false.
Secrets handling.
- Where secrets come from: the environment, or a config file that
rc-mcprefuses to read unless only you can access it (mode 0600). - Logs: JSON lines on stderr, with secrets scrubbed by key name and by value. Tool errors are scrubbed too.
- Doctor: shows only the token's length.
- Where the token is sent: to
RC_URLonly. File downloads follow up to 4 redirects to any host, and redirects to another origin are followed without credentials. Use anhttps://URL:http://is accepted for local testing but sends the token in cleartext. - Treat the PAT like a password. Rocket.Chat tokens have no scopes, so a PAT can do anything your account can.
Revoke it in My Account → Personal Access Tokens when you stop using
rc-mcp.
Chat content is untrusted input. Anyone in a room you read can write text aimed at the model. rc-mcp itself
can't act on it, but other tools in the same Claude Code session might, such as the shell or file edits. Review
actions Claude proposes after reading chat content.
Limitations
Rocket.Chat versions
| Rocket.Chat | Status | Evidence |
|---|---|---|
| 8.9.0 | Tested | The committed fixtures in test/fixtures/8.9.0 were captured by driving the real web client with Playwright. They cover E2EE setup, an encrypted group and DM, thread, edit, quote, text and image uploads, and a room key reset. Unit tests check that the decrypted output equals both the typed text and what the real client rendered. Integration tests run against an 8.9.0 server. |
| Legacy formats (older clients) | Formats verified | Private key v1, legacy bare-msg content (decoded with the rc.v1.aes-sha2 codec) and A128CBC room keys with 12-character key ids are checked against Rocket.Chat's own test vectors; rc.v1.aes-sha2 as a content object is ported from source (test/fixtures/upstream/legacy-v1.json). No older server was run. |
| Any other version | Untested | Likely to work if the formats and REST shapes are unchanged. Regenerate the fixtures to confirm (see Development). |
Matrix federation rooms (m.megolm.v1.aes-sha2) |
Not supported | Messages come back as undecryptable with reason unsupported-algorithm. |
Other limitations
- Old keys: after room key resets the server keeps at most 10 old room keys per member. Messages encrypted
with an older key, or sent before you received the room key, report
room-key-missing. The official client can't read them either. - Suggested keys are used read-only in memory and never accepted on the server. Open the room once in the
official client to accept the key;
rc-mcp doctorlists the rooms where that is needed. When a suggested key comes with old keys (suggestedOldRoomKeys) and your subscription has nooldRoomKeys, those old keys are used too, as the server would adopt them on acceptance, so history from before a room key reset stays readable. - No key shared yet (
no-room-key): until another member's official client is online and shares the key, that room is unreadable. - Rate limits for non-admin tokens: Rocket.Chat limits REST calls per client IP and route. The default is 10
calls per 60 s;
rooms.history,chat.getThreadMessagesandchat.getThreadsListallow 20 per 10 s.rc-mcpwaits for the reset and retries. The CLI retries up to 5 times, gives up on a single wait longer than 120 s and times out a request after 30 s. The MCP server (serve) is less patient so tool calls don't stall: 2 retries, at most 45 s of waiting, 20 s timeout.- The first sync of a large workspace can take minutes. Running
rc-mcp synconce from a terminal backfills every room completely, with the CLI's longer waits. - Other clients behind the same IP share the budget.
- Roles with
api-bypass-rate-limit(admin, bot, app by default) are not limited.
- No live updates: there is no push or websocket; data is synced when a tool runs (see Data flow).
- Subscribed rooms only: public channels you haven't joined are not listed.
- Search coverage:
- Encrypted rooms are searchable only through the local index, and only for history that has been synced.
- Undecryptable messages are not searchable.
- Server-side search covers unencrypted rooms only and, by default, runs only when you pass
rooms(see Data flow). Unencrypted rooms are in the local index anyway.
- Files:
- Downloads have no size limit and no total time limit; a download fails only when no data arrives for 80 s
(four times the
serverequest timeout). The whole file is held in memory: expect a peak of about twice its size, and about four times for an encrypted file while it is decrypted. Cancelling the tool call stops the download. - Encrypted files can be decrypted up to 2 GiB − 1 byte (2147483647 bytes), the most Node's WebCrypto takes
in one operation; larger ones fail with
file-too-largeas soon as the size is known. - Text is returned inline up to 256 KiB by default (
max_inline_bytes, at most 1 MiB). - Images up to 4 MiB are returned as MCP image content and not saved.
- Anything else is saved to disk. In ephemeral mode it is returned inline as an embedded resource instead, up
to 10 MiB; larger files fail with
file-too-large.
- Downloads have no size limit and no total time limit; a download fails only when no data arrives for 80 s
(four times the
- Deletions hidden by "Keep History": with
Message_KeepHistoryon andMessage_ShowDeletedStatusoff, Rocket.Chat hides deleted messages without reporting the deletion through any sync endpoint. Such messages stay in the local index, and in search results, until you re-index the room withrc-mcp sync <room> --full(or thesynctool withfull: true). - Account E2E key reset:
users.resetE2EKeyinvalidates all your login tokens, PATs included, and removes every room key from your subscriptions (E2EKey,E2ESuggestedKeyandoldRoomKeys). Create a new PAT. After the official client has created your new keys, rooms showmissinguntil a member re-shares the room key. History from before the reset is readable only if a member also re-shares the old keys (suggestedOldRoomKeys, whichrc-mcpuses); otherwise it reportsroom-key-missing. - One account per server process.
- Platform: Node.js 24 or newer is required (
node:sqlite). Tested on Linux, including WSL2. On Windows the config-file and data-directory permission checks are skipped;doctor's index-file mode check may still warn there.
Quickstart
Prerequisites
- Node.js 24+ and Claude Code.
- A Rocket.Chat account that has set up E2EE (logged in to the official client once with E2EE enabled), and its E2EE password.
- A personal access token, created by hand in the Rocket.Chat UI: avatar → My Account → Personal Access
Tokens. Enter a name, set the two-factor option to Ignore Two Factor Authentication, then Add. Copy the
Token and Your user Id shown in the dialog; the token is shown only once.
- Without "Ignore Two Factor Authentication", calls can hit a 2FA challenge (
totp-required). - Creating tokens needs the
create-personal-access-tokenspermission, which theuserandadminroles have by default.
- Without "Ignore Two Factor Authentication", calls can hit a 2FA challenge (
Commands (bash or zsh)
# 1. Credentials for this shell (see the note below to keep them out of shell history)
export RC_URL=https://chat.example.com RC_USER_ID=<your-user-id> RC_AUTH_TOKEN=<your-pat> RC_E2EE_PASSWORD='<your E2EE password>'
# 2. Check connectivity, token, E2EE keys and which encrypted rooms are readable
npx -y rocketchat-e2ee-mcp doctor
# 3. Register the server with Claude Code (local scope)
claude mcp add rocketchat -e RC_URL="$RC_URL" -e RC_USER_ID="$RC_USER_ID" -e RC_AUTH_TOKEN="$RC_AUTH_TOKEN" -e RC_E2EE_PASSWORD="$RC_E2EE_PASSWORD" -- npx -y rocketchat-e2ee-mcp
# 4. Start Claude Code
claude
The leading space in step 1 keeps the line out of history in bash (HISTCONTROL=ignorespace) and zsh
(setopt HIST_IGNORE_SPACE). Alternatively read the secrets without echo: read -rs RC_AUTH_TOKEN,
read -rs RC_E2EE_PASSWORD, then export RC_AUTH_TOKEN RC_E2EE_PASSWORD.
Then ask, for example:
- "Search Rocket.Chat for the deploy runbook and summarise the steps, with links."
- "Read this thread and list the decisions: https://chat.example.com/group/handbook/thread/<id>"
- "What did @bob write about electionTimeoutMillis?"
A healthy doctor run looks like this:
rc-mcp doctor
✓ config server https://chat.example.com, user id <your-user-id>, token set (43 chars)
✓ e2ee password RC_E2EE_PASSWORD is set (not shown)
· index stored in /home/you/.local/share/rc-mcp (plaintext of decrypted messages)
✓ node Node.js 24.22.0
✓ server reachable, Rocket.Chat 8.9
✓ authentication token valid for @alice (roles: user)
· rate limits non-admin token: Rocket.Chat limits most REST routes to ~10 calls/min per IP by default; rc-mcp waits and retries
✓ e2ee keys private key unlocked (stored format v2)
✓ rooms 3 subscribed rooms, 2 end-to-end encrypted
✓ encrypted rooms all encrypted rooms are readable
✓ index file /home/you/.local/share/rc-mcp/index.sqlite (mode 600): 0 messages in 3 rooms
Encrypted rooms:
✓ handbook [private-group] key: ok
✓ Bob Brown [direct-message] key: ok
Result: OK
doctor exits with 1 when a check fails (server unreachable, bad token, wrong E2EE password, …) and with 0
otherwise. Warnings, such as an unset E2EE password, unreadable or suggested-key rooms, or an index file with
widened permissions, are printed but don't change the exit code.
Before the npm release
Until rocketchat-e2ee-mcp is published to npm, use one of these in place of npx -y rocketchat-e2ee-mcp, in
steps 3 and 4 and everywhere below:
-
GitHub release tarball:
npx -y https://github.com/alien2003/rocketchat-e2ee-mcp/releases/download/v0.2.0/rocketchat-e2ee-mcp-0.2.0.tgz -
Source build (needs mise):
git clone https://github.com/alien2003/rocketchat-e2ee-mcp && cd rocketchat-e2ee-mcp mise install && mise run setup && mise run buildThen run
node /path/to/rocketchat-e2ee-mcp/dist/cli/main.js. With Claude Code, that isclaude mcp add rocketchat -e … -- node /path/to/rocketchat-e2ee-mcp/dist/cli/main.js.
Once the package is on npm, you can pin a version with npx -y rocketchat-e2ee-mcp@0.2.0.
Other ways to register with Claude Code
The syntax is claude mcp add [options] <name> <commandOrUrl> [args...]. Repeat -e/--env KEY=value for each
variable, and pick a scope with -s/--scope local|user|project.
With literal values, the same as step 4:
claude mcp add rocketchat -e RC_URL=https://chat.example.com -e RC_USER_ID=<id> -e RC_AUTH_TOKEN=<pat> -e RC_E2EE_PASSWORD='<e2ee password>' -- npx -y rocketchat-e2ee-mcp
Values passed with -e are stored in Claude Code's own configuration, outside your repository.
Keep secrets in a 0600 config file instead, so Claude Code's configuration holds only a path. See Configuration for the file format.
claude mcp add rocketchat -e RC_MCP_CONFIG="$HOME/.config/rc-mcp/config.json" -- npx -y rocketchat-e2ee-mcp
Project scope, shared with your team. -s project writes .mcp.json in your project, which you commit.
Never put secrets in it: Claude Code expands ${VAR} in .mcp.json env values from the environment claude
starts in.
-
Either copy
.mcp.json.exampleto.mcp.json, or let Claude Code write it. Single quotes keep the shell from expanding${…}:claude mcp add rocketchat -s project -e RC_URL='${RC_URL}' -e RC_USER_ID='${RC_USER_ID}' -e RC_AUTH_TOKEN='${RC_AUTH_TOKEN}' -e RC_E2EE_PASSWORD='${RC_E2EE_PASSWORD}' -- npx -y rocketchat-e2ee-mcp -
Each teammate exports their own
RC_*values before startingclaude, for example from a private.envloaded withset -a; . ./.env; set +a(see.env.example). Each person reads only what their own account can read.
Rocket.Chat E2EE MCP questions
What tools does Rocket.Chat E2EE MCP provide?
It exposes 12 tools, including list_rooms, get_messages, get_thread, get_message, search.
Can this server send or edit messages?
No, the server is read-only and cannot send, edit, react, mark as read, or accept keys.
Is my E2EE password stored by the server?
No, the server never stores your E2EE password, private key, room keys, or access token.