A comprehensive Model Context Protocol server that provides secure access to Matrix homeserver functionality, enabling clients to interact with Matrix rooms, messages, users, and administration through OAuth 2.0 authentication.

Installation

From Source Code

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

# Install dependencies
npm install

# Build the project
npm run build

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start the server
npm start

Development Mode

# Start with hot reload (OAuth disabled for easier testing)
npm run dev

# Or start with OAuth enabled
ENABLE_OAUTH=true npm run dev

Configuration

VS Code

{
  "servers": {
    "matrix-mcp": {
      "url": "http://localhost:3000/mcp",
      "type": "http",
      "headers": {
        "matrix_access_token": "${input:matrix-access-token}",
        "matrix_user_id": "@<your-matrix-username>:<your-homeserver-domain>",
        "matrix_homeserver_url": "<your-homeserver-url>"
      }
    }
  },
  "inputs": [
    {
      "id": "matrix-access-token",
      "type": "promptString",
      "description": "Your OAuth access token"
    }
  ]
}

Available Tools

Tool	Description
list-joined-rooms	Get all rooms the user has joined
get-room-info	Get detailed information about a room
get-room-members	Show all members of a room
get-room-messages	Get recent messages from a room
get-messages-by-date	Filter messages by date range
identify-active-users	Find most active users by message count
get-user-profile	Get profile information for any user
get-my-profile	Get your own profile information
get-all-users	Show all users known to your client
search-public-rooms	Find public rooms to join
get-notification-counts	Check unread messages and mentions
get-direct-messages	Show all DM conversations
send-message	Send messages to rooms
send-direct-message	Send direct messages to users
create-room	Create new Matrix rooms

Features

• OAuth 2.0 authentication with token exchange support
• 15 Matrix tools organized by functional tiers
• Multi-server support with configurable endpoints
• Real-time operations with ephemeral client management
• Production-ready with comprehensive error handling
• Rich responses with detailed Matrix data

Environment Variables

Required

• ENABLE_OAUTH - Enable OAuth authentication
• MATRIX_HOMESERVER_URL - Matrix homeserver URL
• MATRIX_DOMAIN - Matrix domain
• MATRIX_CLIENT_ID - Matrix client ID
• MATRIX_CLIENT_SECRET - Matrix client secret

Optional

• PORT - Server port
• ENABLE_TOKEN_EXCHANGE - Exchange OAuth tokens for Matrix tokens
• CORS_ALLOWED_ORIGINS - Comma-separated allowed origins (empty = allow all)
• ENABLE_HTTPS - Enable HTTPS
• SSL_KEY_PATH - Path to private key
• SSL_CERT_PATH - Path to certificate
• IDP_ISSUER_URL - Identity provider issuer URL
• IDP_AUTHORIZATION_URL - Identity provider authorization URL

Notes

Supports both OAuth mode for production and development mode for testing. Tools are organized into Tier 0 (read-only) and Tier 1 (actions) levels. Requires Node.js 20+ and access to a Matrix homeserver. The MATRIX_ACCESS_TOKEN header is optional if token exchange is enabled.