matrix-mcp-server

Overview

The Matrix MCP Server is a comprehensive TypeScript implementation that enables secure interaction with Matrix homeserver functionality. It provides both read-only and action tools organized in tiers, allowing clients to list rooms, retrieve messages, manage user profiles, create and join rooms, and send messages with proper authentication. The server supports OAuth 2.0 with token exchange for production deployments and offers development mode for testing. The architecture follows a clean three-layer design with HTTP, MCP, and Matrix layers, ensuring secure ephemeral client management and proper permission checks.

Try asking AI

After installing, here are 6 things you can ask your AI assistant:

• list-joined-rooms

  Get all rooms the user has joined

  Try:List all my roomsTry:Show me the rooms I'm part of
• get-room-inforoomId: string

  Get detailed information about a specific room

  Try:Get info for room !abc:example.comTry:Tell me about the general room
• get-room-messagesroomId: string, limit?: number

  Retrieve recent messages from a room

  Try:Get last 10 messages from #generalTry:Show me recent messages in the team room
• get-user-profiletargetUserId: string

  Get profile information for any Matrix user

  Try:Get profile for @alice:example.comTry:Show me user details for Bob
• search-public-roomssearchTerm?: string, server?: string, limit?: number

  Discover public Matrix rooms to join

  Try:Find rooms about photographyTry:Search for gaming rooms on matrix.org
• send-messageroomId: string, message: string, messageType?: 'text' | 'html' | 'emote', replyToEventId?: string

  Send messages to Matrix rooms

  Try:Hello world in #generalTry:Send a formatted message to the team room
• create-roomroomName: string, isPrivate?: boolean, topic?: string, inviteUsers?: string[], roomAlias?: string

  Create new Matrix rooms with customizable settings

  Try:Create a private room for project planningTry:Make a public room called Photography Chat
• join-roomroomIdOrAlias: string

  Join Matrix rooms by ID or alias

  Try:Join room #general:example.comTry:I want to join the photography community
• leave-roomroomId: string, reason?: string

  Leave a Matrix room with optional reason

  Try:Leave room #generalTry:Exit the spammy room please
• invite-userroomId: string, targetUserId: string

  Invite a user to a Matrix room

  Try:Invite @bob:example.com to our project roomTry:Add Alice to the team room
• set-room-nameroomId: string, roomName: string

  Update the display name of a Matrix room

  Try:Rename room #general to General DiscussionTry:Change room name to Project X
• set-room-topicroomId: string, topic: string

  Update the topic/description of a Matrix room

  Try:Set topic for #general to 'General discussions about anything'Try:Change room description to weekly meeting notes

Comparable tools

Installation

# 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

{
  "mcpServers": {
    "matrix": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "ENABLE_OAUTH": "true",
        "MATRIX_HOMESERVER_URL": "https://matrix.example.com"
      }
    }
  }
}

FAQ

What authentication methods does this MCP server support?

The server supports OAuth 2.0 with token exchange for production deployments and direct access without OAuth for development. OAuth mode is recommended for production deployments as it prevents direct Matrix token exposure.

How do I handle multiple Matrix homeservers?

The server supports multi-homeserver configuration through environment variables. You can configure different endpoints and set up appropriate authentication for each homeserver.

Can I use this MCP server with any Matrix implementation?

Yes, the server is designed to work with any Matrix homeserver implementation including Synapse, Dendrite, and others. It communicates with the homeserver using the standard Matrix client-server API.

Compare matrix-mcp-server with