Skip to content

Getting Started

Prerequisites

You need:

  • Python 3.12+
  • uv
  • an MCP client such as Claude Code or Codex
  • a Matrix homeserver account

Installation

uv tool install matrix-mcp

pipx install matrix-mcp

pip install matrix-mcp

git clone https://github.com/mindroom-ai/matrix-mcp.git
cd matrix-mcp
uv sync --extra dev

Login

Matrix SSO

matrix-mcp auth sso https://mindroom.chat

If the homeserver advertises multiple SSO providers, list them:

matrix-mcp auth providers https://mindroom.chat

Then pass the provider ID explicitly:

matrix-mcp auth sso https://mindroom.chat --idp-id github

SSO over SSH or on a Headless Machine

The SSO flow starts a temporary callback server on the machine running matrix-mcp and waits for the browser to be redirected to it. If that machine is remote — an SSH session, a VM, a container — a browser on your local machine cannot reach the callback address printed in the SSO URL.

Pin the callback port on the remote machine:

matrix-mcp auth sso https://mindroom.chat --callback-port 8765

While that command waits, forward the port from your local machine in a second terminal:

ssh -N -L 8765:127.0.0.1:8765 remote-host

Open the printed SSO URL in your local browser. After login, the homeserver redirects to http://127.0.0.1:8765/callback, which SSH forwards to the waiting command on the remote machine.

If port forwarding is not an option, print the SSO URL with a placeholder redirect URL:

matrix-mcp auth sso-url https://mindroom.chat http://127.0.0.1:8765/callback

Open that URL in any browser and log in. The final redirect to http://127.0.0.1:8765/callback?loginToken=... fails to load — that is expected. Copy the loginToken value from the browser address bar and exchange it on the remote machine right away (login tokens are single-use and expire within minutes):

matrix-mcp auth login-token https://mindroom.chat syt_...

If matrix-mcp is also installed on the machine with the browser, log in there:

matrix-mcp auth sso https://mindroom.chat
matrix-mcp config-path

Then copy the file printed by config-path to the path that matrix-mcp config-path prints on the remote machine, creating the directory if needed.

Encrypted rooms do not work with copied credentials: the device's encryption keys stay on the machine that logged in, and the remote machine refuses to publish new ones for the same device. Use one of the other methods when you need encrypted rooms on the remote machine.

Existing Matrix Access Token

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

Password Auth

matrix-mcp auth password https://mindroom.chat @alice:mindroom.chat

End-to-End Encryption

SSO, password, and login-token logins create a new Matrix device for Matrix MCP and publish its encryption keys, so encrypted rooms work from the start. auth token reuses the device that the access token belongs to; encryption then works only if no other client has published keys for that device. Messages sent before the login cannot be decrypted unless you import room keys exported from another client:

matrix-mcp e2ee import-keys element-keys.txt

See End-to-End Encryption for details.

Configure an MCP Client

claude mcp add matrix -- matrix-mcp serve

codex mcp add matrix -- matrix-mcp serve

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

Verify

Ask the MCP client to call matrix_whoami. It should return the Matrix user and device saved by the login command.