mjknowles/matrix-mcp-server

A comprehensive **Model Context Protocol (MCP) server** that provides secure access to Matrix homeserver functionality. Built with TypeScript, this server enables MCP clients to interact with Matrix rooms, messages, users, and more through a standardized interface.
Features
- 🔐 **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
- 🚀 **Production Ready** with comprehensive error handling
- 📊 **Rich Responses** with detailed Matrix data
Quick Start
Prerequisites
- **Node.js 20+** and npm
- **Matrix homeserver** access (Synapse, Dendrite, etc.)
- **MCP client** (Claude Desktop, VS Code with MCP extension, etc.)
Installation
Development Mode
Available Tools
📖 Tier 0: Read-Only Tools
**Room Tools**
- **list-joined-rooms** - Get all rooms the user has joined
- _No parameters required_
- Returns room names, IDs, and member counts
- **get-room-info** - Get detailed room information
- roomId (string): Matrix room ID (e.g., !roomid:domain.com)
- Returns name, topic, settings, creator, and member count
- **get-room-members** - List all members in a room
- roomId (string): Matrix room ID
- Returns display names and user IDs of joined members
**Message Tools**
- **get-room-messages** - Retrieve recent messages from a room
- roomId (string): Matrix room ID
- limit (number, default: 20): Maximum messages to retrieve
- Returns formatted message content including text and images
- **get-messages-by-date** - Filter messages by date range
- roomId (string): Matrix room ID
- startDate (string): ISO 8601 format (e.g., 2024-01-01T00:00:00Z)
- endDate (string): ISO 8601 format
- Returns messages within the specified timeframe
- **identify-active-users** - Find most active users by message count
- roomId (string): Matrix room ID
- limit (number, default: 10): Maximum users to return
- Returns users ranked by message activity
**User Tools**
- **get-user-profile** - Get profile information for any user
- targetUserId (string): Target user's Matrix ID (e.g., @user:domain.com)
- Returns display name, avatar, presence, and shared rooms
- **get-my-profile** - Get your own profile information
- _No parameters required_
- Returns your profile, device info, and room statistics
- **get-all-users** - List all users known to your client
- _No parameters required_
- Returns display names and user IDs from client cache
**Search Tools**
- **search-public-rooms** - Discover public rooms to join
- searchTerm (string, optional): Filter by name or topic
- server (string, optional): Specific server to search
- limit (number, default: 20): Maximum rooms to return
- Returns room details, topics, and member counts
**Notification Tools**
- **get-notification-counts** - Check unread messages and mentions
- roomFilter (string, optional): Specific room ID to check
- Returns unread counts, mentions, and recent activity
- **get-direct-messages** - List all DM conversations
- includeEmpty (boolean, default: false): Include DMs with no recent messages
- Returns DM partners, last messages, and unread status
✏️ Tier 1: Action Tools
**Messaging Tools**
- **send-message** - Send messages to rooms
- roomId (string): Matrix room ID
- message (string): Message content
- messageType (enum: "text" | "html" | "emote", default: "text"): Message formatting