matrix-mcp-server

What is matrix-mcp-server?

A comprehensive Model Context Protocol (MCP) server that provides secure access to Matrix homeserver functionality. Built with TypeScript, it enables MCP clients to interact with Matrix rooms, messages, users, and more through a standardized interface.

How to use matrix-mcp-server?

Install dependencies via npm, build the project, configure environment variables in a .env file, and start the server with npm start. Clients connect via HTTP transport, providing headers for Matrix user ID, homeserver URL, and access token (or OAuth). The server offers two authentication modes: OAuth mode for production and development mode for testing.

Key features of matrix-mcp-server

• OAuth 2.0 authentication with token exchange support
• 15 Matrix tools organized by functionality tiers
• Multi‑homeserver support with configurable endpoints
• Real‑time operations with ephemeral client management
• Comprehensive error handling and input validation
• Rich responses with detailed Matrix data

Use cases of matrix-mcp-server

• List rooms the user has joined and retrieve room details
• Send messages, direct messages, and manage room membership
• Search public rooms and filter messages by date range
• Identify most active users in a room by message count
• Create, join, leave, and administer Matrix rooms

FAQ from matrix-mcp-server

What is OAuth mode and when should I use it?

OAuth mode uses full OAuth 2.0 integration with your identity provider, supports token exchange for Matrix homeserver authentication, and is recommended for production deployments.

What are the runtime requirements?

Node.js 20+ and npm, access to a Matrix homeserver (Synapse, Dendrite, etc.), and an MCP client like Claude Desktop or VS Code with MCP extension.

Where does user and room data reside?

All data lives on the Matrix homeserver. The server creates ephemeral Matrix clients that authenticate, perform operations, and clean up automatically; no data is stored locally.

How are permissions and security handled?

All Matrix clients are ephemeral, OAuth prevents direct token exposure, room power levels and permissions are respected, and input validation uses Zod schemas. CORS is also configurable.

Can I use matrix-mcp-server without OAuth?

Yes. In development mode (ENABLE_OAUTH=false) you can use direct Matrix access tokens, but this is not recommended for production.