mcp-server-matrix
MCP server for Matrix — interact with Matrix homeservers via Model Context Protocol
Ask AI about mcp-server-matrix
Powered by Claude · Grounded in docs
I know everything about mcp-server-matrix. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
mcp-server-matrix
A Model Context Protocol (MCP) server for Matrix — the open, decentralized communication protocol.
Built on matrix-nio, this server lets any MCP-compatible AI assistant (Claude, OpenClaw, etc.) send and read messages, manage rooms, and interact with any Matrix homeserver (Synapse, Dendrite, Conduit).
Features
| Tool | Description |
|---|---|
send_message | Send a message (text, HTML, or Markdown) with optional reply |
read_messages | Read recent messages (with pagination) |
get_messages_by_date | Get messages filtered by date range |
list_rooms | List all joined rooms |
get_room_info | Room details — name, topic, members, encryption status |
get_room_members | List joined members with display names and avatars |
get_notification_counts | Unread and mention counts per room |
get_direct_messages | List DM conversations with unread status |
send_direct_message | Send a DM (auto-creates room if needed) |
get_user_profile | User profile — display name, avatar |
join_room | Join a room by ID or alias |
leave_room | Leave a room |
create_room | Create a new room (with optional invites) |
invite_user | Invite a user to a room |
send_reaction | React to a message with an emoji |
resolve_alias | Resolve #alias:server to a room ID |
Installation
pip install mcp-server-matrix
Or with uv:
uvx mcp-server-matrix
Configuration
Set environment variables:
| Variable | Required | Description |
|---|---|---|
MATRIX_HOMESERVER | Yes | Homeserver URL (e.g. https://matrix.org) |
MATRIX_USER | Yes | Full user ID (e.g. @bot:matrix.org) |
MATRIX_PASSWORD | Yes* | Account password |
MATRIX_ACCESS_TOKEN | Yes* | Access token (alternative to password) |
MATRIX_STORE_PATH | No | Path for nio session store (default: ~/.mcp-server-matrix/nio_store/) |
MCP_LOG_LEVEL | No | Log level: DEBUG, INFO, WARNING, ERROR (default: INFO) |
* Provide either MATRIX_PASSWORD or MATRIX_ACCESS_TOKEN.
Usage
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"matrix": {
"command": "mcp-server-matrix",
"env": {
"MATRIX_HOMESERVER": "https://matrix.example.com",
"MATRIX_USER": "@bot:example.com",
"MATRIX_PASSWORD": "your-password"
}
}
}
}
Claude Code
{
"mcpServers": {
"matrix": {
"command": "mcp-server-matrix",
"env": {
"MATRIX_HOMESERVER": "https://matrix.example.com",
"MATRIX_USER": "@bot:example.com",
"MATRIX_ACCESS_TOKEN": "syt_..."
}
}
}
}
OpenClaw
Add to openclaw.json:
{
"mcp": {
"servers": {
"matrix": {
"command": "mcp-server-matrix",
"env": {
"MATRIX_HOMESERVER": "https://matrix.example.com",
"MATRIX_USER": "@bot:example.com",
"MATRIX_PASSWORD": "your-password"
}
}
}
}
}
Direct (stdio)
export MATRIX_HOMESERVER=https://matrix.example.com
export MATRIX_USER=@bot:example.com
export MATRIX_PASSWORD=your-password
mcp-server-matrix
Examples
Once connected, your AI assistant can:
- Read messages: "What are the latest messages in #general?"
- Send messages: "Send 'Hello everyone!' to #announcements"
- Manage rooms: "Create a room called 'Project X' and invite @alice:matrix.org"
- Get info: "How many members are in #team-chat?"
Supported Homeservers
Tested with:
- Synapse (reference implementation)
- Should work with any spec-compliant homeserver (Dendrite, Conduit, etc.)
Requirements
- Python 3.10+
- A Matrix account on any homeserver
- Network access to the homeserver
License
MIT
