This MCP server exposes a Matrix-focused API that lets MCP clients interact with Matrix homeserver functionality through a standardized interface. It supports OAuth 2.0 authentication with token exchange, and provides a rich set of tools organized into tiers: Tier 0 offers read-only access to room, message, user, and search data, while Tier 1 adds actions such as sending messages, creating and managing rooms, and inviting or moderating participants. Use the provided endpoints to fetch room information, list members, retrieve messages, and perform operations like sending messages or creating rooms, all while leveraging the token management and real-time capabilities provided by the MCP layer.

To use, start the server (after configuring environment variables per the .env example). If OAuth is enabled, obtain an access token via your identity provider and exchange it through the MCP flow as required. Clients can then call the available MCP tools, e.g., list-joined-rooms, get-room-info, get-room-messages, send-message, create-room, invite-user, and manage room settings, depending on the user’s permissions and the tool tier. The server supports multi-homeserver setups, so you can configure multiple Matrix endpoints and route actions accordingly.

Prerequisites:

• Node.js 20+ and npm
• A Matrix homeserver (e.g., Synapse, Dendrite)
• A compatible MCP client (Claude Desktop, VS Code MCP extension, etc.)

Installation steps:

1. Clone the repository git clone <repository-url> cd matrix-mcp-server

2. Install dependencies npm install

3. Build the project npm run build

4. Configure environment cp .env.example .env

   Edit .env with your settings (see example values in README)

5. Start the server npm start

Development mode (optional):

• Start with hot reload and OAuth disabled for easier testing npm run dev
• Or start with OAuth enabled ENABLE_OAUTH=true npm run dev

Environment variables and configuration:

• Core: PORT, ENABLE_OAUTH, ENABLE_TOKEN_EXCHANGE, CORS_ALLOWED_ORIGINS
• HTTPS: ENABLE_HTTPS, SSL_KEY_PATH, SSL_CERT_PATH (if using TLS)
• OAuth: IDP_ISSUER_URL, IDP_AUTHORIZATION_URL, IDP_TOKEN_URL, OAUTH_CALLBACK_URL
• Matrix: MATRIX_HOMESERVER_URL, MATRIX_DOMAIN, MATRIX_CLIENT_ID, MATRIX_CLIENT_SECRET If you encounter token exchange issues, verify your IDP URLs and client credentials, and ensure your MCP client is configured to request the required scopes. For development testing, you can disable OAuth (ENABLE_OAUTH=false) to bypass the OAuth flow, but do not use this in production. When running behind reverse proxies, ensure proper header forwarding and CORS settings. The server supports multi-homeserver setups; you can add additional entries under mcpServers with their own command/args/env blocks.