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, read threads and history, reply, share files, and manage rooms, including end-to-end encrypted ones.
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 |
| "Read the deploy thread and reply with the fix I just pushed." | matrix_read_thread, matrix_send_message |
"Post coverage.html to the CI room and ask the reviewer to take a look." |
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 and invite Bob and Carol." | matrix_create_room, matrix_search_users |
| "Find where we picked the release date and show me the discussion around it." | matrix_read_history, matrix_get_event_context |
Highlights
- 🧰 30 tools. Reading, threads, history, unread catch-up, replies, reactions, edits, redactions, invitations, rooms, 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, reading never marks messages read, receipts are private by default, and transfers are size-bounded.
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 |
| Reading | matrix_read_room_recent, matrix_read_thread, matrix_read_history, matrix_get_event_context |
| Writing | matrix_send_message, matrix_reply, matrix_react, matrix_edit_message, matrix_redact_event |
| Membership | matrix_list_room_members, matrix_search_users, matrix_invite_user, matrix_list_invitations, matrix_join_room, matrix_leave_room, matrix_create_room |
| 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.
1 maintainer
Metadata
1 maintainer
Release files for matrix-mcp 0.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| matrix_mcp-0.9.1.tar.gz | 286.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matrix_mcp-0.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 348.8 kB
Release files / matrix_mcp-0.9.1.tar.gz
| Download URL | matrix_mcp-0.9.1.tar.gz |
|---|---|
| Size | 286.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
58432852bb82748415303ea11d98bc02baf7ac4e99ee52832e8c062776c1b0bd
|
|
BLAKE2b-256 checksum How to use checksums |
e44dc36f2f04fc75ba9b52fe70a42cb1586bf3d5df31999cadfeeeb956f9387d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 10, 2026.
Transparency logRelease files / matrix_mcp-0.9.1-py3-none-any.whl
| Download URL | matrix_mcp-0.9.1-py3-none-any.whl |
|---|---|
| Size | 62.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a3d7baf1c6eb6404e3dd1f64b69c2cd90b15778edad03ab9eaa14c8eb840f6b
|
|
BLAKE2b-256 checksum How to use checksums |
c3ae905987c9909add29d180a00b7ca26430098bf35cb390082dc6d466e93c12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 10, 2026.
Transparency log
