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).
| 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 |
pip install mcp-server-matrixOr with uv:
uvx mcp-server-matrixSet 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.
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"
}
}
}
}{
"mcpServers": {
"matrix": {
"command": "mcp-server-matrix",
"env": {
"MATRIX_HOMESERVER": "https://matrix.example.com",
"MATRIX_USER": "@bot:example.com",
"MATRIX_ACCESS_TOKEN": "syt_..."
}
}
}
}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"
}
}
}
}
}export MATRIX_HOMESERVER=https://matrix.example.com
export MATRIX_USER=@bot:example.com
export MATRIX_PASSWORD=your-password
mcp-server-matrixOnce 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?"
Tested with:
- Synapse (reference implementation)
- Should work with any spec-compliant homeserver (Dendrite, Conduit, etc.)
- Python 3.10+
- A Matrix account on any homeserver
- Network access to the homeserver
MIT