rocket-cli

Rocket.Chat bridge with a local SQLite/FTS5 cache — CLI for humans, MCP server for LLM agents.

On first read a room is backfilled (up to 500 messages / 30 days). Subsequent reads hit chat.syncMessages for deltas (60 s TTL), then serve from SQLite — zero network on cache-fresh rooms. Full-text search runs across all cached rooms locally via FTS5; when scoped to a room it falls back to the server and ingests the results into the cache.

graph TB
    Agent["LLM Agent\n(Claude · MCP stdio)"]
    Human["Human\n(CLI)"]

    subgraph Core["Core"]
        RD["RoomDirectory"]
        SE["SyncEngine"]
        SS["SearchService"]
        AT["Attention\n(mentions · unread)"]
        ED["EmojiDirectory"]
    end

    subgraph Cache["SQLite cache"]
        MSG["messages\n+ FTS5 index"]
        META["rooms · emojis"]
    end

    RC["Rocket.Chat\n(REST API)"]

    Agent -->|"MCP tools"| Core
    Human -->|"commands"| Core

    Core -->|"cache hit: 0 network, sub-ms"| Cache
    Core -->|"miss/stale: backfill + syncMessages deltas"| RC
    RC -->|"write-through"| Cache

    Agent <-->|"open_url / permalinks"| RC

    classDef cache fill:#f0f7ff,stroke:#4a90d9,stroke-width:2px
    class Cache cache

Architecture at a glance: agents and humans share one Core; the SQLite cache absorbs most reads; the server is only hit on cache miss or write.

Loading philosophy — network follows user value, never ambient

Data is loaded in priority order of what you asked for; the cache accelerates but never blocks, and the tool never fetches history nobody requested:

• Triage is always shallow. get_unread / get_mentions / get_attention fetch only the slice after each room's last-read watermark (ts > ls) — usually a handful of messages — not a full backfill. Answering "what's unread?" stays fast even on a cold cache with many unread rooms.

• Reading serves instantly, revalidates in the background. get_messages / list_threads use stale-while-revalidate: a cached room is served immediately while a delta sync refreshes it in the background (the response carries "refreshing": true when that happens — the data may be seconds stale). A totally-cold room blocks only for one history page (≈100 messages, enough to answer) and then that room's remaining backfill completes in the background — because reading a room is the intent to have its recent history.

• Deep history is explicit only. Full backfill happens when you ask for it: rocket-cli sync [room] | --all (blocking, human choice) or the sync_history MCP tool (an agent calls it when a task needs history beyond the recent window — e.g. "summarize the last month"). There is no ambient background warmer — the MCP server never progressively fills the database for data nobody asked about.

What needs my attention

The headline feature: one call answers "what did I miss?". get_attention (MCP) / rocket-cli attention (CLI) fuses mentions of you, unread DMs, unread thread replies, and unread channel messages into a single prioritized, deduplicated digest — a message that both mentions you and is unread appears once, in the mentions section, flagged alsoUnread. Every item carries a clickable Rocket.Chat link, and the whole flow is strictly read-only (it never clears a single unread badge). Paste any of those links back to the agent via open_url (or rocket-cli open <url>) and you get the surrounding conversation plus the ids needed to reply — a full triage-to-reply round-trip without leaving the chat.

Related MCP server: SynapBus

Install

Requirements: Node >= 20, npm

git clone <repo-url>   # or your fork/path
cd rocket-cli
npm install
npm run build
npm link               # optional: puts `rocket-cli` on your PATH

After npm link, examples below can use rocket-cli instead of node dist/cli.js.

Get your credentials

1. Open Rocket.Chat in your browser → click your avatar (top-left) → My Account → Personal Access Tokens

2. If the section is missing: an admin must enable the API_Enable_Personal_Access_Tokens setting, and your role needs the create-personal-access-tokens permission

3. Name the token (e.g. rocket-cli), check Ignore Two Factor Authentication (without it, API calls may demand TOTP codes the CLI cannot answer), then click Add

4. Copy both the token and the user ID — they appear together in the same confirmation dialog, and the token is shown only once

5. Copy the example env file and fill in your values:

   cp .env.example .env

   Set ROCKETCHAT_URL, ROCKETCHAT_TOKEN, and ROCKETCHAT_USER_ID. The CLI auto-loads .env from the directory you run it in; real environment variables always take precedence.

Quickstart

rocket-cli rooms        # lists rooms you're subscribed to — verifies auth
rocket-cli sync --all   # initial backfill into the local cache
rocket-cli messages general -n 20
rocket-cli search "deploy"

Cache reset: rm ~/.local/share/rocket-cli/cache.db* — next run re-syncs from the server.

Multiple servers (profiles)

Connect to more than one Rocket.Chat server with named profiles. Each profile carries its own URL, token, user id, and an isolated database — data is never mixed across servers.

Profiles live in ~/.config/rocket-cli/profiles.json (XDG-aware; XDG_CONFIG_HOME honored). The file holds tokens, so it is written chmod 600 (owner read/write only) — keep it that way.

{
  "defaultProfile": "test",
  "profiles": {
    "test": {
      "url": "https://test.example.com",
      "token": "REPLACE_WITH_TEST_TOKEN",
      "userId": "REPLACE_WITH_TEST_USER_ID"
    },
    "work": {
      "url": "https://chat.company.com",
      "token": "REPLACE_WITH_WORK_TOKEN",
      "userId": "REPLACE_WITH_WORK_USER_ID",
      "readOnly": true
    }
  }
}

Optional per-profile fields: db (explicit database path), readOnly, syncTtlSeconds, backfillLimit, emojiImages.

# List profiles (name, url, db path, read-only, * = default). Tokens never printed.
rocket-cli profiles

# Add a profile (writes profiles.json with mode 600)
rocket-cli profiles --add test --url https://test.example.com --token <t> --user-id <id>
rocket-cli profiles --add work --url https://chat.company.com --token <t> --user-id <id> --read-only

# Set the default profile (used when no --profile / ROCKET_CLI_PROFILE is given)
rocket-cli profiles --default test

# Use a profile for any command
rocket-cli --profile work rooms
rocket-cli --profile work attention
ROCKET_CLI_PROFILE=work rocket-cli rooms   # env equivalent (handy for MCP)

Resolution order: an explicit --profile flag (or ROCKET_CLI_PROFILE env) selects a profile → the profile's connection identity (url, token, userId, db) is authoritative — ambient env vars and cwd .env values for those fields are ignored. Tuning knobs (ROCKET_CLI_SYNC_TTL_SECONDS, ROCKET_CLI_BACKFILL_LIMIT, ROCKET_CLI_EMOJI_IMAGES, ROCKET_CLI_READ_ONLY) may still be overridden by env when the profile omits them. With no profile and only env vars, behavior is exactly as before. A defaultProfile applies when nothing is explicitly selected and ROCKETCHAT_URL is not already in the environment (so legacy env-only setups remain untouched).

Per-profile database isolation: a profile's db defaults to ~/.local/share/rocket-cli/<profile>.db (override with the profile's db field). No profile uses the legacy ~/.local/share/rocket-cli/cache.db. A database file is bound on first use to the (server URL, user id) it was synced from — opening it later under a different identity is a hard error (it tells you which profile/db/server mismatched and how to fix it), so cross-profile contamination is impossible.

Read-only mode ("readOnly": true, or --read-only on profiles --add) is the safety mode for production / company servers. It blocks every server write:

• MCP serve registers 15 tools instead of 18 — send_message, add_reaction, and upload_file are not exposed. All reads (including download_attachment and sync_history, which only write local disk / the local cache) still work.

• CLI send, upload, and watch --notify refuse with a clear error and exit 1.

• scripts/seed.ts aborts immediately (it writes to the server).

Two MCP registrations for Claude Code

Register one MCP server per profile, each serve with its ROCKET_CLI_PROFILE env — no flags needed. Make work read-only so the agent can read your company server but never post to it:

{
  "mcpServers": {
    "rocketchat-test": {
      "command": "node",
      "args": ["/absolute/path/to/rocket-cli/dist/cli.js", "serve"],
      "env": { "ROCKET_CLI_PROFILE": "test" }
    },
    "rocketchat-work": {
      "command": "node",
      "args": ["/absolute/path/to/rocket-cli/dist/cli.js", "serve"],
      "env": { "ROCKET_CLI_PROFILE": "work" }
    }
  }
}

See .mcp.json.example for a copy-paste starting point.

CLI usage

All commands accept --json for machine-readable output and --profile <name> to select a named connection profile (see Multiple servers).

# List rooms you belong to
node dist/cli.js rooms
node dist/cli.js rooms --type channel
node dist/cli.js rooms --filter infra

# Sync a room or all rooms
node dist/cli.js sync #dev
node dist/cli.js sync --all
node dist/cli.js sync --all --force   # bypass TTL, re-fetch everything

# Read messages
node dist/cli.js messages #dev -n 50
node dist/cli.js messages #dev -n 20 --before 2026-06-01T00:00:00.000Z

# Show everything unread since you last read each room (read-only — never clears badges)
node dist/cli.js unread
node dist/cli.js unread --limit 20 --no-threads

# One-call triage: mentions + unread DMs + threads + channels, prioritized & deduplicated
node dist/cli.js attention
node dist/cli.js attention --since-days 2 --limit 20 --all-broadcasts

# Just the messages that mention you, across all cached rooms (read-only)
node dist/cli.js mentions
node dist/cli.js mentions --since-days 14 --all-broadcasts

# Show the conversation around a message id (from search, mentions, or a link)
node dist/cli.js context <message-id>
node dist/cli.js context <message-id> --before 20 --after 10

# Paste any Rocket.Chat web link to open its content + how to reply
node dist/cli.js open "https://chat.example.com/channel/general?msg=<id>"

# Full-text search (cross-room by default)
node dist/cli.js search "deploy error"
node dist/cli.js search "deploy error" --room #dev
node dist/cli.js search "deploy error" --room #dev --author jsmith --limit 10

# Send a message
node dist/cli.js send #dev "Hello team"
node dist/cli.js send #dev "Fixed in the next build" --thread <parent-message-id>

# List threads in a room; show a specific thread
node dist/cli.js threads general -n 10
node dist/cli.js thread <parent-message-id>

# Watch for messages matching a query (local FTS)
node dist/cli.js watch "deploy error" --once
node dist/cli.js watch "incident" --room #ops --interval 30

# Upload a file to a room
node dist/cli.js upload general /path/to/report.pdf --text "Q2 report"

# Download an attachment (use the link from `messages` output: [file] name -> /file-upload/…)
node dist/cli.js download /file-upload/abc123/report.pdf --out /tmp/report.pdf

# List custom emojis registered on the server
node dist/cli.js emojis
node dist/cli.js emojis --filter rocket
node dist/cli.js emojis --sync                  # force a refresh, ignore TTL
node dist/cli.js emojis --export /tmp/emoji     # save every emoji image to a directory

# Start the MCP stdio server (used by Claude Code / Claude Desktop)
node dist/cli.js serve

# Manage named connection profiles (multiple servers)
node dist/cli.js profiles
node dist/cli.js profiles --add work --url https://chat.company.com --token <t> --user-id <id> --read-only

rooms flags

sync flags

messages flags

unread flags

Read-only: lists messages with ts newer than each room's server-side last-read watermark (the marker the UI sets when you open a room). It never calls subscriptions.read and never clears unread badges. Rooms with no read marker fall back to a newest-N approximation, flagged in the output.

Which rooms count as unread mirrors the Rocket.Chat sidebar exactly. A room is surfaced when it has an unread signal (unread count, the alert flag, or unread thread replies) and its "Hide unread counter" room setting (hideUnreadStatus) is off — the same (alert || unread || tunread) && !hideUnreadStatus predicate the sidebar uses (apps/meteor/client/sidebar/hooks/useRoomList.ts). The one exception the UI keeps for a hidden room is an explicit mention: a room with "Hide unread counter" on still appears when you are mentioned in it (userMentions/groupMentions, or a thread reply that mentions you) and "Hide mention" is off, matching getSubscriptionUnreadData.ts. Such a room is labeled hidden room, mentioned in the output and carries hiddenMentioned: true in the JSON report. Use --all to ignore the hide setting and list every room with any unread signal (the pre-parity behavior).

attention flags

Read-only one-call triage. Runs the mentions and unread views, then fuses them into prioritized sections — MENTIONS, DIRECT MESSAGES, THREADS, CHANNELS — deduplicated by message id (a mentioned message that is also unread is shown once, under mentions, flagged also unread). Every item carries a clickable link. Never clears a badge.

mentions flags

context flags

open flags

Paste any Rocket.Chat web link — a message, a thread, or a plain channel — and open resolves it, prints the surrounding conversation (target marked →), and shows how to reply.

search flags

send flags

threads flags

thread flags

watch flags

upload flags

download flags

emojis flags

Image caching can be disabled with ROCKET_CLI_EMOJI_IMAGES=false (metadata only); --export and get_custom_emoji then degrade to names/aliases plus the server image URL.

MCP server for Claude Code

Add to .mcp.json in your project root (or ~/.claude/mcp.json for global):

{
  "mcpServers": {
    "rocketchat": {
      "command": "node",
      "args": ["/absolute/path/to/rocket-cli/dist/cli.js", "serve"],
      "env": {
        "ROCKETCHAT_URL": "${ROCKETCHAT_URL}",
        "ROCKETCHAT_TOKEN": "${ROCKETCHAT_TOKEN}",
        "ROCKETCHAT_USER_ID": "${ROCKETCHAT_USER_ID}"
      }
    }
  }
}

Use ${VARIABLE} env-expansion so the token is read from your shell environment, not stored literally in the file. Never commit a .mcp.json with a real token.

For Claude Desktop, add an equivalent entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) with the same command/args/env structure.

See .mcp.json.example at the repo root for a copy-paste starting point.

CLI alternative — register with the claude CLI instead of editing .mcp.json manually:

claude mcp add rocketchat \
  -e ROCKETCHAT_URL=https://chat.example.com \
  -e ROCKETCHAT_TOKEN=your-token \
  -e ROCKETCHAT_USER_ID=your-user-id \
  -- node /absolute/path/to/rocket-cli/dist/cli.js serve

The -e flag sets env vars scoped to this MCP server; they are not exported to your shell. Run claude mcp add --help for scope and transport options.

MCP tools

Eighteen tools are exposed to the LLM agent (fifteen under a read-only profile — the three write tools send_message, add_reaction, and upload_file are then withheld; see Multiple servers):

get_messages and list_threads return an envelope with room, syncedThrough, and coverage so the agent knows the freshness and depth of the cached data, plus "refreshing": true when the answer was served from cache while a background sync revalidates it (data may be seconds stale). Thread parents in get_messages carry a replyCount; pass that message's id as threadId to get_thread_messages.

Attachment links appear in get_messages output as [file] name -> /file-upload/…; pass the part after -> as fileUrl to download_attachment.

Agent skills

skills/ ships six Claude Code skills that teach an agent how to drive rocket-cli (via the MCP tools, or the --json CLI as a fallback):

• rocket-attention — triage "what needs my attention" (mentions, unread DMs/threads/channels).

• rocket-catchup — summarize or recap one specific room or thread.

• rocket-find — full-text search for a known message, link, or file.

• rocket-link — open any pasted Rocket.Chat URL and show how to act on it.

• rocket-send — send/reply/react/upload, with read-only degradation.

• rocket-guide — reference: tool table, cache model, profiles, CLI↔MCP mapping.

Install them with ./scripts/install-skills.sh — it symlinks each skills/<name>/ into ~/.claude/skills/, so edits in this repo propagate live. Re-running is safe; ./scripts/install-skills.sh --uninstall removes only the symlinks that point back into this repo.

Architecture

1. Lazy backfill — first access to a room fetches up to 500 messages / 30 days via channels.history / groups.history / im.history.

2. Delta sync — subsequent reads call chat.syncMessages(lastUpdate) (60 s TTL), applying edits and deletions into the local store.

3. FTS5 search — BM25-ranked full-text search across all cached rooms; if results are thin and a room is specified, falls back to chat.search and ingests the server results into the cache.

4. Write-through sends — chat.postMessage response is upserted into the local DB, so the sent message appears in the next get_messages without a sync round-trip.

5. Threads on demand — ensureThreadLoaded checks tcount vs local reply count and backfills gaps via chat.getThreadMessages.

DB location: ~/.local/share/rocket-cli/cache.db (XDG data home) for the default env-only config; each named profile uses its own ~/.local/share/rocket-cli/<profile>.db (see Multiple servers). Override either with ROCKET_CLI_DB or a profile's db field.

Server load and rate limits

How rocket-cli stays gentle by construction

rocket-cli is designed to minimize server pressure:

Rocket.Chat's built-in rate limiter

Rocket.Chat applies a per-endpoint, per-IP limit out of the box:

Both values are tunable at runtime without a restart. When rocket-cli receives a 429, it backs off using the server's own reset signal (X-RateLimit-Reset header or details.seconds in the error body). Rocket.Chat does not send a Retry-After header.

Important caveat for admin / bot tokens

Accounts that hold the api-bypass-rate-limit permission are not throttled by the server at all. By default this permission is granted to the admin, bot, and app roles. If you run rocket-cli under an admin Personal Access Token (a common setup), the server-side limiter is effectively off — rocket-cli's own 2-concurrent-request cap is the only brake.

This is fine in practice (see the table above), but worth knowing: the "10 calls/60 s" numbers below do not apply to your session if your token belongs to an admin or bot account.

Practical throughput numbers

After the first sync the cache absorbs routine reads; typical interactive use generates a handful of delta calls per session regardless of token type.

Environment variables

Validating against your own server

rocket-cli's most important features — unread, mentions, threads, DM unreads — only have meaningful state when other users have generated activity for you. Your own messages never mark your own rooms unread or mention yourself. To exercise the tool end-to-end you need a realistic multi-user workspace.

Two scripts under scripts/ do this against any server where you hold an admin PAT:

• scripts/seed.ts — creates four personas (ana.dev, bruno.qa, carla.pm, diego.ops), public channels (#engineering, #random, #incidents), a private group (#leadership), DMs and a multi-party DM to you, then posts a believable conversation fabric as those personas: threads (incl. one mentioning you and a 30+ reply long thread), an edited message, a deleted message, an @all/@here broadcast, file + image uploads, a custom-emoji reaction, a quote, rich-text and a ~3000-char message, plus negative cases that must stay invisible to you (a #secret-ops channel you are not in, and a persona↔persona DM). It is idempotent: re-running checks-before-creating and will not duplicate content.

• scripts/validate.ts — the automated true-usage test. It runs the built CLI with an isolated temp cache (ROCKET_CLI_DB), cold-syncs every room, then asserts the seeded state surfaces correctly: attention shows the mentions / DM unreads / unread thread, unread lists the seeded rooms, mentions finds 3+, search hits thread content, thread reads the long thread fully, open resolves a permalink with reply affordances, the edited text is reflected, the deleted message is gone, and the negative cases never leak. Each assertion prints a pass/fail line; the script exits non-zero on any failure.

  • Sidebar parity: on a default-config server (Unread_Count = user_and_group_mentions_only) a plain-chatter channel sets alert: true but unread: 0; validate asserts such a channel (#random, no @jean mention) still appears in unread/attention — flagged activityOnly — instead of being dropped.

# requires: a built CLI (npm run build) + admin PAT in .env
npm run seed        # create the multi-user state (idempotent)
npm run validate    # cold-sync into a temp cache and assert everything
npm run validate:full   # both, back to back

Persona passwords are generated once and stored in scripts/.seed-credentials.json (gitignored, mode 0600); the path and password are printed to stderr only, never to stdout. The scripts live outside the src tsconfig rootDir; typecheck them with npx tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck --types node scripts/*.ts.

Known issues

See docs/KNOWN_ISSUES.md.