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.

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/:

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