Skip to main content
Glama
rocketchat-mcp-server

rocketchat-mcp-server

by GavinTomlins

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_ONLY mode (write tools hidden), per-tool readOnlyHint/ destructiveHint annotations, 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 stdio

Configuration

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 needed

Live 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 live

Pin/react tests skip automatically when the account lacks those permissions.

Deployment

  • Docker / Podman: Dockerfile builds a non-root OCI image. A systemd quadlet unit is in deploy/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/:

New consequential decisions are recorded as additional numbered ADRs.

Documentation

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 tools
add_reactionB

Add an emoji reaction to a message (e.g. :thumbsup:).

Inputs: emoji (required), message_id (required). Returns: object

delete_messageC
Destructive

Delete a message (needs room_id and message_id). Destructive.

Inputs: room_id (required), message_id (required). Returns: object

download_fileA
Read-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_digestA
Read-only

Summarise channel activity over the last N hours (active users, threads, files).

Inputs: channel (required), hours. Returns: object

get_channel_infoA
Read-only

Get details for a channel or private group by name or ID.

Inputs: channel (required). Returns: object

get_channel_membersC
Read-only

List members of a channel or private group.

Inputs: channel (required), count, offset. Returns: object

get_channel_messagesB
Read-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_mentionsB
Read-only

Get messages that mention the authenticated user in a channel.

Inputs: channel (required), count, offset, compact. Returns: object

get_message_contextC
Read-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_messagesB
Read-only

Get pinned messages in a channel.

Inputs: channel (required), count, offset, compact. Returns: object

get_thread_messagesC
Read-only

Get the replies in a thread.

Inputs: thread_id (required), count, compact. Returns: object

get_unread_channelsA
Read-only

List channels with unread messages, sorted by unread count descending.

Inputs: no named parameters. Returns: object

get_user_infoA
Read-only

Get details for a user by username.

Inputs: username (required). Returns: object

list_channelsA
Read-only

List public channels. Optional query filters by name substring.

Inputs: count, query, offset. Returns: object

list_dmsB
Read-only

List direct-message conversations.

Inputs: count, offset. Returns: object

list_groupsA
Read-only

List private groups the authenticated user belongs to.

Inputs: count, offset. Returns: object

list_joined_channelsB
Read-only

List channels the authenticated user has joined.

Inputs: count, offset. Returns: object

list_room_filesC
Read-only

List files shared in a room.

Inputs: channel (required), count, offset. Returns: object

list_usersB
Read-only

List users. Optional query filters by name substring.

Inputs: count, query, offset. Returns: object

mark_as_readB
Idempotent

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_messagesC
Read-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

    B3.2/5.0

    Scored across 28 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    Related MCP Servers