rocketchat-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.

Related MCP server: mcp-room

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.get plus one rooms.get.

• Backfill: rooms.history, 100 messages per page, newest first.

• Incremental: chat.syncMessages returns 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_messages and get_thread refresh a room whose last sync is older than 60 s. get_messages returns only history that the index holds without gaps; paging back with before backfills older messages as needed.

  • search with rooms refreshes those rooms the same way. Without rooms, it syncs changed rooms at most every 5 minutes. refresh: false skips all network work (no sync, and no server search unless include_server_search: true is 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_message and get_thread fetch them live (chat.getMessage, chat.getThreadMessages). get_file always 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, search also queries Rocket.Chat's chat.search when you pass rooms (up to 10 of the named rooms), or, with include_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 in notes.

• 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) and search answer from the index and add a notes entry 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

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 -wal and -shm files next to it. The directory is mode 0700 and is tightened if it is wider. The files are 0600, and the process runs with umask 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=1 keeps the index in memory, and get_file then writes nothing to disk.

  • rc-mcp purge deletes the index and saved files. It also works while RC_MCP_EPHEMERAL is set, to remove what earlier non-ephemeral runs left behind.

  • rc-mcp doctor warns if the index file has become group- or world-readable.

  • Full-disk encryption is recommended.

• get_file returns text within max_inline_bytes and 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 purge removes them;

  • ephemeral mode: returned inline as an MCP embedded resource (up to 10 MiB), never written to disk.

• rc-mcp export writes plaintext Markdown to stdout, or with -o to 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_file fetches 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-mcp uses 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-mcp uses 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/logout revokes the calling token, PATs included;

  • chat.ignoreUser changes your subscription;

  • im.history / im.messages called with a username can create a DM;

  • e2e.acceptSuggestedGroupKey would 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-mcp refuses 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_URL only. File downloads follow up to 4 redirects to any host, and redirects to another origin are followed without credentials. Use an https:// 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

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 doctor lists the rooms where that is needed. When a suggested key comes with old keys (suggestedOldRoomKeys) and your subscription has no oldRoomKeys, 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.getThreadMessages and chat.getThreadsList allow 20 per 10 s.

  • rc-mcp waits 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 sync once 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 serve request 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-large as 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.

• Deletions hidden by "Keep History": with Message_KeepHistory on and Message_ShowDeletedStatus off, 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 with rc-mcp sync <room> --full (or the sync tool with full: true).

• Account E2E key reset: users.resetE2EKey invalidates all your login tokens, PATs included, and removes every room key from your subscriptions (E2EKey, E2ESuggestedKey and oldRoomKeys). Create a new PAT. After the official client has created your new keys, rooms show missing until 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, which rc-mcp uses); otherwise it reports room-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-tokens permission, which the user and admin roles have by default.

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 build

  Then run node /path/to/rocketchat-e2ee-mcp/dist/cli/main.js. With Claude Code, that is claude 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.

1. Either copy .mcp.json.example to .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

2. Each teammate exports their own RC_* values before starting claude, for example from a private .env loaded with set -a; . ./.env; set +a (see .env.example). Each person reads only what their own account can read.

Tools

All tools are read-only (readOnlyHint: true, destructiveHint: false) and return JSON text. You can refer to a room by id, name (handbook), display name, or @username for a DM. Message ids can be any id-like token (imported messages, for example from Slack, have longer ids), and pasted URLs with ?msg=<id> or /thread/<id> work wherever a message or thread id is expected (get_message, get_thread, get_file.message_id, search.thread_id). file_id must be a bare file id.

Dates are ISO 8601: 2026-03-01 (midnight UTC), 2026-03-01T12:00:00Z or 2026-03-01T14:00:00+02:00. A date-time without Z or an offset is read in the local time zone of the machine running rc-mcp. Values are validated and converted to UTC; an invalid value returns invalid-argument. after is inclusive and before is exclusive, so before: "2026-03-01" stops at 2026-03-01 00:00 UTC and leaves out 1 March. The CLI's --after / --since and --before / --until work the same way.

get_file only downloads a file it can find in a message or in a room's upload list (groups.files, channels.files, im.files); anything else is file-not-found. file_id must match [A-Za-z0-9_-]{1,64}. If you pass both ids, the message must carry that file.

Resources: rocketchat://room/{rid} returns a Markdown transcript of the room's 50 most recent top-level messages, decrypted. Thread replies are left out; thread roots show their reply count and thread id. The resource list contains every subscribed room.

Message objects have these fields:

• id, room_id, room, ts, author, text, permalink;

• thread_id, reply_count, edited_at, system_type;

• quotes[], attachments[] (file_id, name, type, size, …), encrypted;

• undecryptable {reason, hint, key_id?} in place of text when a message can't be decrypted. Tools never guess that content.

Errors come back with isError: true and one shape:

{ "error": { "code": "room-not-found", "message": "No room matching \"ops\" among the rooms this account is subscribed to.", "hint": "Call list_rooms to see room ids and names." } }

The codes are:

• room-not-found, invalid-argument, message-deleted;

• from get_file: file-not-found, file-key-missing, file-too-large (ephemeral mode, or an encrypted file above 2 GiB − 1 byte), and undecryptable when the file's message or metadata can't be decrypted;

• rocketchat-<code>, for example rocketchat-unauthorized, rocketchat-rate-limited, rocketchat-network or rocketchat-timeout;

• e2ee-<reason>;

• internal-error.

Arguments that don't match a tool's schema (for example limit: 1000) are rejected by the MCP SDK before the tool runs. That error is plain text, such as MCP error -32602: Input validation error: …, still with isError: true.

Examples

These are abridged results from the 8.9.0 fixtures. The server URL and the room name (handbook-mva1woss) are simplified.

search with { "query": "deploy runbook", "rooms": ["handbook"] }:

{
  "query": "deploy runbook",
  "count": 1,
  "results": [
    {
      "id": "Zd97mTM23F4efdEg8",
      "room_id": "6ad1459708d9d91a69c55ade",
      "room": "handbook",
      "ts": "2026-10-15T21:28:59.374Z",
      "author": "Alice Anders (@alice)",
      "text": "Deploy runbook: run `make deploy` from the release branch, then check /healthz on every node.",
      "reply_count": 2,
      "encrypted": true,
      "permalink": "https://chat.example.com/group/handbook?msg=Zd97mTM23F4efdEg8",
      "snippet": "«Deploy» «runbook»: run `make «deploy»` from the release branch, then check /healthz on every node.",
      "source": "index"
    }
  ],
  "index": { "rooms": 3, "messages": 19 }
}

get_thread with { "url": "https://chat.example.com/group/handbook/thread/Zd97mTM23F4efdEg8" }. The first reply was encrypted before a room key reset and the second one after it; both decrypt, the first via oldRoomKeys:

{
  "room": { "id": "6ad1459708d9d91a69c55ade", "name": "handbook", "type": "private-group", "encrypted": true, "key_status": "ok" },
  "root": { "id": "Zd97mTM23F4efdEg8", "author": "Alice Anders (@alice)", "text": "Deploy runbook: run `make deploy` from the release branch, then check /healthz on every node.", "reply_count": 2 },
  "total_replies": 2,
  "returned": 2,
  "replies": [
    { "author": "Bob Brown (@bob)", "text": "Thread reply: remember to bump the version in package.json before `make deploy`.", "thread_id": "Zd97mTM23F4efdEg8" },
    { "author": "Bob Brown (@bob)", "text": "Post-reset thread reply (bob): version bump is now automated by CI.", "thread_id": "Zd97mTM23F4efdEg8" }
  ]
}

get_file with { "message_id": "<id of a file message>" } returns two content items. The first is the metadata:

{ "file_id": "<file id>", "name": "release-checklist.md", "type": "text/markdown", "size": 96, "encrypted": true, "integrity": "verified", "message_id": "<id>", "inline": true }

The second is the decrypted file text.

A message the account can't decrypt:

{ "id": "<id>", "text": "", "encrypted": true, "undecryptable": { "reason": "room-key-missing", "hint": "Encrypted with a room key this account does not hold (e.g. sent before you got access, or before a room key reset older than the 10 kept keys).", "key_id": "<key id>" } }

CLI

Every CLI command uses the same configuration as the server. The command is rc-mcp after npm install -g rocketchat-e2ee-mcp. Otherwise run npx -y rocketchat-e2ee-mcp <command>, or node dist/cli/main.js <command> from a source build.

rc-mcp [serve]                       MCP server over stdio (the default command)
rc-mcp doctor [--json]               connectivity, token, E2EE key state, unreadable rooms and why
rc-mcp sync [room] [--full] [--max-messages <n>] [--json]
rc-mcp search <query...> [-r, --room <room...>] [-f, --from <user...>] [--after <date>] [--before <date>]
                         [-n, --limit <n>] [--no-refresh] [--json]
rc-mcp export <room> [-t, --thread <id>] [--since <date>] [--until <date>] [--format md] [-o, --output <file>]
rc-mcp purge [-y, --yes]
rc-mcp --version | --help

Numeric options (--max-messages, -n) must be positive integers.

rc-mcp sync                                   # bring the index up to date
rc-mcp search postgres failover -r handbook -n 5
rc-mcp export handbook -t Zd97mTM23F4efdEg8 -o runbook.md

2026-10-15 20:23  handbook  Alice Anders (@alice)
  «Deploy» «runbook»: run `make «deploy»` from the release branch, then check /healthz on every node.
  https://chat.example.com/group/handbook?msg=Zd97mTM23F4efdEg8
1 result(s)

The output above is from rc-mcp search deploy runbook.

Exit codes: 0 success, 1 error (also a failed doctor check or a room that failed in sync), 2 configuration error.

Configuration

Settings are read from environment variables and an optional JSON config file. Environment variables take precedence over the file. rc-mcp does not read .env files by itself; see .env.example.

Config file. The file must not be readable or writable by group or others; rc-mcp refuses it otherwise and tells you to run chmod 600. Unknown keys are rejected. rc-mcp never writes this file.

mkdir -p ~/.config/rc-mcp && install -m 600 /dev/null ~/.config/rc-mcp/config.json && $EDITOR ~/.config/rc-mcp/config.json

{
  "url": "https://chat.example.com",
  "userId": "<your-user-id>",
  "authToken": "<your-personal-access-token>",
  "e2eePassword": "<your-e2ee-password>",
  "ephemeral": false,
  "logLevel": "info"
}

Where data lives:

Removing local data:

• rc-mcp purge (or purge --yes in scripts) deletes the index and saved files, also while RC_MCP_EPHEMERAL is set.

• RC_MCP_EPHEMERAL=1 avoids writing the index and attachments at all; each server start then syncs from scratch.

Troubleshooting

Run rc-mcp doctor first. It checks each step and says what to fix.

Reason reference. The first four reasons describe the account's E2EE state: they appear in list_rooms (e2ee.reason), in a room's key_detail, in rc-mcp doctor and as e2ee-<reason> error codes. The others are per-message undecryptable.reason values (and file errors).

Development

mise install && mise run setup      # Node, pnpm, compose CLI; then dependencies + headless Chromium into node_modules
mise run check                      # lint + typecheck + unit tests

To run several tasks in one call, separate them with :::, as in mise run lint ::: typecheck. Without the separator, mise run lint typecheck would pass typecheck to lint as an argument.

There are three test layers. No test encrypts with this project's code to prove compatibility.

• Unit (mise run test, offline):

  • crypto is checked against the committed real-client fixtures and Rocket.Chat's legacy vectors;

  • the index and sync run against a fake Rocket.Chat that serves the captured responses;

  • MCP tools are tested through an in-memory transport;

  • a guard checks that rc-mcp serve writes only JSON-RPC to stdout.

• Integration (mise run rc:up, then mise run test:ground-truth once, then mise run test:integration): runs against a Rocket.Chat 8.9.0 + MongoDB compose stack as alice, bob, carol and the admin rcadmin. The ground-truth run gives the users real E2EE keys and data and records itself in .local/stack.json, which the integration tests require. Covers REST pagination, chat.syncMessages, downloads, the real rate limiter, and rc-mcp serve over stdio driven by the MCP client SDK.

• Ground truth (mise run test:ground-truth): Playwright drives the real web client through E2EE setup, messages, uploads and a room key reset. The suite then checks that the decrypted output equals what was typed and what the client rendered.

Other tasks: mise run dev (server from source with auto-reload), mise run build, mise run rc:down, mise run fixtures:generate.

Supporting another Rocket.Chat version:

1. Set RC_VERSION in .mise.toml.

2. Run mise run rc:down && mise run rc:up && mise run fixtures:generate, then the tests.

3. Read the source diff of apps/meteor/client/lib/e2ee between the two versions.

See CONTRIBUTING.md for the contribution workflow and docs/adr/0001-architecture.md for the design.

License

MIT © alien2003