Metadata-Version: 2.5
Name: matrix-mcp
Version: 0.10.0
Summary: A Matrix MCP server for connecting coding agents to Matrix and MindRoom conversations.
Project-URL: Homepage, https://matrix-mcp.mindroom.chat/
Project-URL: Documentation, https://matrix-mcp.mindroom.chat/
Project-URL: Repository, https://github.com/mindroom-ai/matrix-mcp
Project-URL: Issues, https://github.com/mindroom-ai/matrix-mcp/issues
Project-URL: Changelog, https://github.com/mindroom-ai/matrix-mcp/releases
Author: MindRoom
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,claude,codex,e2ee,matrix,mcp,model-context-protocol,sso
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: anyio>=4
Requires-Dist: certifi>=2024.2.2
Requires-Dist: cryptography>=45
Requires-Dist: fastmcp==3.2.4
Requires-Dist: filelock>=3.18
Requires-Dist: httpx>=0.28
Requires-Dist: mindroom-nio[e2e]>=0.25.3
Requires-Dist: platformdirs>=4.3
Requires-Dist: py-key-value-aio[filetree,memory]>=0.4.4
Requires-Dist: pydantic-settings>=2.9
Requires-Dist: pydantic>=2.11
Requires-Dist: rich>=14.0
Requires-Dist: typer>=0.19
Provides-Extra: dev
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pre-commit>=4; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.4; extra == 'dev'
Requires-Dist: ruff>=0.13; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<picture>
  <source media="(prefers-reduced-motion: no-preference)" srcset="https://raw.githubusercontent.com/mindroom-ai/matrix-mcp/main/docs/assets/logo.svg" />
  <img src="https://raw.githubusercontent.com/mindroom-ai/matrix-mcp/main/docs/assets/logo-static.svg" alt="Matrix MCP logo" width="128" />
</picture>

# Matrix MCP

**Give your AI agent a seat in every Matrix room.**

A full-featured [MCP](https://modelcontextprotocol.io/) server for [Matrix](https://matrix.org/).
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](https://img.shields.io/pypi/v/matrix-mcp.svg)](https://pypi.org/project/matrix-mcp/)
[![Python Versions](https://img.shields.io/pypi/pyversions/matrix-mcp.svg)](https://pypi.org/project/matrix-mcp/)
[![CI](https://github.com/mindroom-ai/matrix-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mindroom-ai/matrix-mcp/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-matrix--mcp.mindroom.chat-0b6f86)](https://matrix-mcp.mindroom.chat/)
[![MCP](https://img.shields.io/badge/MCP-server-0b6f86)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mindroom-ai/matrix-mcp/blob/main/LICENSE)

**[Documentation](https://matrix-mcp.mindroom.chat/)** ·
[Getting Started](https://matrix-mcp.mindroom.chat/getting-started/) ·
[Tool Reference](https://matrix-mcp.mindroom.chat/usage/) ·
[Encryption](https://matrix-mcp.mindroom.chat/encryption/) ·
[Hosted Mode](https://matrix-mcp.mindroom.chat/hosted/)

</div>

## Quick Start

```bash
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](https://matrix-mcp.mindroom.chat/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](https://matrix-mcp.mindroom.chat/hosted/) 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](https://matrix-mcp.mindroom.chat/usage/) has arguments, examples, and limits for each tool.

## Development

```bash
uv sync --extra dev
uv run pytest
```

See [Contributing](https://matrix-mcp.mindroom.chat/contributing/) for linting, type checks, docs, and releases.

## Built by MindRoom

<a href="https://mindroom.chat"><img src="https://raw.githubusercontent.com/mindroom-ai/matrix-mcp/main/docs/assets/mindroom.png" alt="MindRoom logo" width="64" align="left" /></a>

Matrix MCP is built by [MindRoom](https://mindroom.chat), 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.

<br clear="left" />

MIT licensed.
