matrix-mcp 0.5.0

A Matrix MCP server for connecting coding agents to Matrix and MindRoom conversations.

Matrix MCP

Local-first Matrix access for MCP clients.

Matrix MCP lets Claude Code and other MCP clients read and write Matrix rooms. It is intended to make MindRoom conversations available to local coding agents without giving hosted agents access to the local filesystem.

Install

uv tool install matrix-mcp

For local development:

uv sync --extra dev

Login

Matrix SSO:

matrix-mcp auth sso https://matrix.example.com

If the homeserver advertises multiple SSO providers, list their provider IDs:

matrix-mcp auth providers https://matrix.example.com

Then pass the provider ID explicitly:

matrix-mcp auth sso https://matrix.example.com --idp-id github

If your homeserver is behind an access gateway that requires extra request headers, pass them during login. They are stored with the Matrix credentials and reused by MCP tools:

matrix-mcp auth sso https://matrix.example.com \
  --header "X-Access-Client-Id: ..." \
  --header "X-Access-Client-Secret: ..."

If the gateway header is short-lived, store a command that prints the current header value instead. The command is re-run when Matrix MCP creates a client for tool calls:

matrix-mcp auth sso https://matrix.example.com \
  --header-command "X-Access-Token: access-gateway-cli token --app https://matrix.example.com"

For homeservers behind Cloudflare Access, matrix-mcp can configure the dynamic cf-access-token header for you. This uses the local cloudflared CLI to read an existing token or start a Cloudflare Access login when needed:

matrix-mcp auth sso https://matrix.example.com --cloudflare-access

Existing Matrix access token:

matrix-mcp auth token https://matrix.example.com @alice:example.com "$MATRIX_ACCESS_TOKEN" --device-id DEVICEID

Password auth, when enabled by the homeserver:

matrix-mcp auth password https://matrix.example.com @alice:example.com

Credentials are stored in the user config directory reported by:

matrix-mcp config-path

Remove stored credentials:

matrix-mcp auth logout

Claude Code

Add the local MCP server:

claude mcp add matrix -- matrix-mcp serve

Codex

Add the local MCP server:

codex mcp add matrix -- matrix-mcp serve

The server runs over stdio. It does not expose a local HTTP port during normal MCP operation.

Tools

• matrix_whoami: show the configured Matrix user/device.
• matrix_list_rooms: list rooms joined by the authenticated user.
• matrix_read_room_recent: read recent text events from a room.
• matrix_read_thread: read a Matrix thread root and its recent text replies.
• matrix_send_message: send a text message or local file, optionally as a Matrix thread reply.

Rooms and events returned by read/list tools include stable numeric id fields. Thread replies also include thread_ref, which is the numeric event ref of the thread root. Use these integers in later tool calls instead of copying raw Matrix IDs:

matrix_read_room_recent(room_id=1)
matrix_read_thread(room_id=1, thread_id=42)
matrix_send_message(room_id=1, body="reply", thread_id=42)

The tool instructions tell clients to prefer read tools first and only send messages when the user explicitly asks.

Development

uv run --extra dev pytest
uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
uv run --extra dev mypy src tests
uv run --extra dev ty check
uv build