rocketchat-mcp-server
Provides tools for managing Rocket.Chat channels, messages, threads, direct messages, files, users, and analytics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rocketchat-mcp-server list recent messages in #general"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
rocketchat-mcp-server
A FastMCP (Python) server for Rocket.Chat — 28 tools with AI governance,
observability, and monitoring built in. A ground-up rewrite of the Go server
rocketchat-mcp-go, applying the systematic MCP-server approach in
ADR 0001.
Highlights
28 tools across channels, messages, threads, DMs, files, users, and analytics.
Token economy: message grouping (consecutive same-user merge), compact mode, parallel thread expansion, server-side channel digests.
Governance:
READ_ONLYmode (write tools hidden), per-toolreadOnlyHint/destructiveHintannotations, optional human-in-the-loop approval for consequential writes, structured audit events, and a bearer-token gateway.Observability: structlog JSON logs with secret redaction, per-tool logging middleware,
/metrics(Prometheus), optional OpenTelemetry tracing, and/healthz+/readyz.Security: SSRF host guard + 25 MB cap on downloads, filename escaping on uploads, URL scheme validation, bounded pagination. See the security review.
Related MCP server: Slack MCP Server
Quick start
uv sync --extra dev --extra metrics
export ROCKETCHAT_URL="https://chat.example.com"
export ROCKETCHAT_AUTH_TOKEN="<personal access token>"
export ROCKETCHAT_USER_ID="<user id>"
# HTTP (Streamable) transport on :8000, endpoint /mcp
uv run rocketchat-mcp --mode http
# stdio transport (local MCP clients)
uv run rocketchat-mcp --mode stdioConfiguration
Go-compatible env vars are preserved: ROCKETCHAT_URL, ROCKETCHAT_AUTH_TOKEN,
ROCKETCHAT_USER_ID, READ_ONLY, MCP_PORT. New settings use the RCMCP_
prefix — notably RCMCP_APPROVE_WRITES, RCMCP_GATEWAY_TOKENS
(token:principal,...), RCMCP_READ_ONLY, RCMCP_ENABLE_METRICS,
RCMCP_LOG_JSON. See config.py.
Security note: the HTTP transport should sit behind the bearer-token gateway (
RCMCP_GATEWAY_TOKENS) and TLS termination (Traefik/nginx). The server holds a single Rocket.Chat identity — every authorised caller shares its permission ceiling.
Development
uv run ruff check .
uv run mypy src
uv run pytest -m "not live" # default: respx-mocked, no live server neededLive integration tests
tests/test_live.py exercises the server against a real Rocket.Chat. They
are excluded from the default suite and CI, and only touch a dedicated test
channel (default mcp-test), cleaning up every message they create. The
configured account must be a member of that channel.
RCMCP_LIVE=1 RCMCP_TEST_CHANNEL=mcp-test \
ROCKETCHAT_URL=... ROCKETCHAT_AUTH_TOKEN=... ROCKETCHAT_USER_ID=... \
uv run pytest -m livePin/react tests skip automatically when the account lacks those permissions.
Deployment
Docker / Podman:
Dockerfilebuilds a non-root OCI image. A systemd quadlet unit is indeploy/quadlet/.Release: tag
v*triggers the multi-arch nexus push workflow.
Architecture Decision Records
This server is built to a documented, systematic standard. The design rationale
lives in ADRs under docs/adr/:
ADR 0001 — A systematic approach to building MCP servers — the house standard for architecture, AI governance, observability, and engineering practice that this repository implements.
ADR 0002 — Per-principal upstream identity (multi-tenant) — opt-in per-caller Rocket.Chat credentials so actions are attributable.
New consequential decisions are recorded as additional numbered ADRs.
Documentation
System design — FastMCP adoption design, tool parity, delivery phases.
Bot identity — message alias vs a dedicated bot account, and how to set one up.
Cutover runbook — migrating from the Go server and retiring it.
Architecture Decision Records — see above.
Security review — Snickers / Snyk agent-security findings and their dispositions.
Provenance
A ground-up FastMCP (Python) rewrite of the Go server rocketchat-mcp-go,
applying lessons from openproject-gt-mcp-server (layered architecture,
observability, human-in-the-loop) and redmine-mcp-server (tag-based tool
visibility, {error, hint, code} envelope, secret scrubbing). Tracked under
OpenProject AI and Automation / EPIC #9810.
Available Tools
28 toolsadd_reactionB
Add an emoji reaction to a message (e.g. :thumbsup:).
Inputs: emoji (required), message_id (required). Returns: object
delete_messageCDestructive
Delete a message (needs room_id and message_id). Destructive.
Inputs: room_id (required), message_id (required). Returns: object
download_fileARead-only
Download a file from the configured Rocket.Chat server.
Returns an image, plain text, or a base64 blob depending on content type. Only fetches from the configured server host (SSRF-guarded, 25 MB cap).
Inputs: url (required).
edit_messageC
Edit an existing message (needs room_id and message_id).
Inputs: text (required), room_id (required), message_id (required). Returns: object
get_channel_digestARead-only
Summarise channel activity over the last N hours (active users, threads, files).
Inputs: channel (required), hours. Returns: object
get_channel_infoARead-only
Get details for a channel or private group by name or ID.
Inputs: channel (required). Returns: object
get_channel_membersCRead-only
List members of a channel or private group.
Inputs: channel (required), count, offset. Returns: object
get_channel_messagesBRead-only
Get channel history, newest first.
group merges consecutive same-user messages within 60s (token saver).
expand_threads fetches thread replies. compact truncates to id/user/text/ts.
Inputs: channel (required), count, group, offset, +2 more. Returns: object
get_mentionsBRead-only
Get messages that mention the authenticated user in a channel.
Inputs: channel (required), count, offset, compact. Returns: object
get_message_contextCRead-only
Get N messages before and after a target message (target flagged is_target).
Inputs: channel (required), message_id (required), after, before, +1 more. Returns: object
get_pinned_messagesBRead-only
Get pinned messages in a channel.
Inputs: channel (required), count, offset, compact. Returns: object
get_thread_messagesCRead-only
Get the replies in a thread.
Inputs: thread_id (required), count, compact. Returns: object
get_unread_channelsARead-only
List channels with unread messages, sorted by unread count descending.
Inputs: no named parameters. Returns: object
get_user_infoARead-only
Get details for a user by username.
Inputs: username (required). Returns: object
list_channelsARead-only
List public channels. Optional query filters by name substring.
Inputs: count, query, offset. Returns: object
list_dmsBRead-only
List direct-message conversations.
Inputs: count, offset. Returns: object
list_groupsARead-only
List private groups the authenticated user belongs to.
Inputs: count, offset. Returns: object
list_joined_channelsBRead-only
List channels the authenticated user has joined.
Inputs: count, offset. Returns: object
list_room_filesCRead-only
List files shared in a room.
Inputs: channel (required), count, offset. Returns: object
list_usersBRead-only
List users. Optional query filters by name substring.
Inputs: count, query, offset. Returns: object
mark_as_readBIdempotent
Mark all messages in a channel as read (clears the unread counter).
Inputs: channel (required). Returns: object
pin_messageC
Pin a message.
Inputs: message_id (required). Returns: object
reply_to_threadA
Reply into a thread. channel is auto-resolved from the parent if omitted.
Inputs: text (required), thread_id (required), channel. Returns: object
search_messagesCRead-only
Search for text within a channel.
Inputs: channel (required), search_text (required), count, compact. Returns: object
send_dmA
Send a direct message to a user (creates the DM room if needed).
Inputs: text (required), username (required). Returns: object
send_fileB
Upload a base64-encoded file to a room.
Inputs: channel (required), content (required), filename (required), message, +1 more. Returns: object
send_messageC
Post a message to a channel or group.
Inputs: text (required), channel (required). Returns: object
unpin_messageC
Unpin a message.
Inputs: message_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Each tool targets a distinct action or resource, with clear separation between message operations, channel queries, user info, and file handling. Even similar tools like get_channel_messages and search_messages have different intents, and descriptions prevent confusion.
All tool names follow a consistent verb_noun pattern in snake_case, such as add_reaction, delete_message, list_channels, and send_dm. The only minor variation is reply_to_thread, which still adheres to the same convention.
28 tools is above the typical 5-15 range for MCP servers, but the coverage of Rocket.Chat operations (messages, channels, users, files, etc.) justifies the count. It's borderline heavy but not excessive.
The toolset covers core messaging, channel reading, and user lookups, but lacks room creation/deletion (e.g., create_channel, delete_room) and administrative actions. This creates noticeable gaps for automation of the full lifecycle.
Related MCP Connectors
MCP server for Sendbird — chat users, channels, members, and messages from your AI client.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA production-ready MCP server built with FastAPI, providing an enhanced tool registry for creating, managing, and documenting AI tools for Large Language Models (LLMs).34-
- FlicenseNot gradedqualityDmaintenanceA comprehensive Slack integration server that enables sending messages, managing channels, uploading files, and running Pomodoro timers through FastMCP v2.2-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents and LLMs to interact with the ICON MCP v104 API through standardized tools. The server is built on FastMCP for efficient async handling and includes Docker support for easy deployment.-
- FlicenseNot gradedqualityDmaintenanceMCP server for Rocket.Chat, enabling AI agents to interact with Rocket.Chat workspaces via tools like listing users, sending messages, and managing channels.2-