Skip to main content
Matrix MCP logo

Matrix MCP

Give your AI agent a seat in every Matrix room.

A full-featured MCP server for Matrix. Claude Code, Codex, and any other MCP client can catch up on your rooms, search, read threads, reply, react, share files, and run rooms. End-to-end encrypted rooms work too, though the homeserver cannot search them.

PyPI Python Versions CI Docs MCP License

Documentation · Getting Started · Tool Reference · Encryption · Hosted Mode

Quick Start

uv tool install matrix-mcp
matrix-mcp auth sso https://mindroom.chat   # your homeserver; opens a browser for SSO

claude mcp add matrix -- matrix-mcp serve   # Claude Code
codex mcp add matrix -- matrix-mcp serve    # Codex

Then ask your agent "What did I miss in the release room?"

The server talks to your MCP client over stdio and opens no local port. Getting Started covers SSO providers, logging in over SSH or on a headless machine, password and access-token login, and homeservers behind access gateways such as Cloudflare Access.

What You Can Ask

Ask your agent Tools it reaches for
"Catch me up: which rooms need me, and what was I mentioned in?" matrix_get_unread, matrix_read_thread
"Find where we picked the release date and show me the discussion around it." matrix_search_messages, matrix_get_event_context
"Which threads in #dev are still active? Reply to the deploy one with my fix." matrix_list_threads, matrix_send_message
"Did anyone 👍 my proposal, and has Bob read it yet?" matrix_get_reactions, matrix_get_read_receipts
"DM Bob the coverage report from this repo." matrix_create_dm, matrix_send_message
"Download the screenshot Alice posted and tell me what's broken." matrix_read_room_recent, matrix_download_media
"Spin up a room for this incident, invite Carol, and pin the runbook link." matrix_create_room, matrix_send_message, matrix_pin_message

Highlights

  • 🧰 43 tools. Search, threads, history, unread catch-up, reactions, read receipts, replies, edits, direct chats, spaces, pins, moderation, profiles, and media.
  • 🔒 End-to-end encryption. Matrix MCP is its own Matrix device: encrypted rooms just work, files included, and older keys import from Element.
  • 🔑 Every login your server allows. Matrix SSO (even over SSH), password, login token, or access token, including homeservers behind Cloudflare Access and other gateways.
  • 🌐 Local or hosted. stdio for local agents, or authenticated HTTP where every user signs in with their own Matrix account through OAuth and Matrix SSO. Container images on GHCR.
  • #️⃣ Light on context. Rooms and events get short numeric refs, so agents write room_id=3 instead of copying long Matrix IDs.
  • 🛡️ Careful by design. Every tool declares whether it writes and whether it is destructive, reading never marks messages read, receipts are private by default, transfers are size-bounded, and it won't kick, ban, or demote you.

As far as we know, Matrix MCP is the only Matrix MCP server that runs both as a local server with end-to-end encryption and as a multi-user hosted service where everyone signs in with their own Matrix account.

Tools

Area Tools
Session and rooms matrix_whoami, matrix_list_rooms, matrix_get_room_info, matrix_set_room_name, matrix_set_room_topic, matrix_set_room_avatar, matrix_get_space_hierarchy
Reading matrix_read_room_recent, matrix_read_thread, matrix_list_threads, matrix_read_history, matrix_get_event_context, matrix_search_messages, matrix_get_reactions, matrix_get_read_receipts
Writing matrix_send_message, matrix_reply, matrix_react, matrix_edit_message, matrix_redact_event, matrix_pin_message, matrix_unpin_message
Membership matrix_list_room_members, matrix_search_users, matrix_invite_user, matrix_list_invitations, matrix_join_room, matrix_leave_room, matrix_create_room, matrix_create_dm
Moderation matrix_get_power_levels, matrix_set_power_level, matrix_kick_user, matrix_ban_user, matrix_unban_user
Profile matrix_get_profile, matrix_set_display_name, matrix_set_avatar
Media matrix_upload_media, matrix_download_media, matrix_send_media
Catch-up matrix_get_unread, matrix_mark_read

All actions use the connected account's Matrix permissions. The Tool Reference has arguments, examples, and limits for each tool.

Development

uv sync --extra dev
uv run pytest

See Contributing for linting, type checks, docs, and releases.

Built by MindRoom

MindRoom logo

Matrix MCP is built by MindRoom, open-source AI agents that live in Matrix. We use it to bring our local coding agents into the same rooms as our teammates and our MindRoom agents. It works with any Matrix homeserver; no MindRoom account needed.


MIT licensed.

Metadata

Release files for matrix-mcp 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for matrix-mcp 0.10.0
File Size Uploaded Provenance Actions
matrix_mcp-0.10.0.tar.gz 320.5 kB With provenance Details for matrix_mcp-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for matrix-mcp 0.10.0
File Interpreter ABI Platform Actions
matrix_mcp-0.10.0-py3-none-any.whl Python 3 none any Details for matrix_mcp-0.10.0-py3-none-any.whl

Total release size: 397.7 kB

Release files / matrix_mcp-0.10.0.tar.gz

Download URL matrix_mcp-0.10.0.tar.gz
Size 320.5 kB
Tags Source
SHA-256 checksum
How to use checksums
3c024e0fdcf511b96e89a0af7708fdc66d1559d810b1a51f1ea760be7211d35e
BLAKE2b-256 checksum
How to use checksums
b8344844ccfbede61f8f8d8310a12dfd4c109d8f7e0fdd830a754e8fea3a2a0b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / matrix_mcp-0.10.0-py3-none-any.whl

Download URL matrix_mcp-0.10.0-py3-none-any.whl
Size 77.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1838758b7830e8bdc3e08dd8b89aa43a258e1ac33fd8f97af041ec7deeac7fb3
BLAKE2b-256 checksum
How to use checksums
cdf318e2c7312d56b9291e769f814ee7bcf8f732370bfb9bd4380eb70a4c46e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for matrix-mcp 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for matrix_mcp-0.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page