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.
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=3instead 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.