About mcp-server-matrix
mcp-server-matrix is an MCP server in the Communication category: a local-first MCP configuration manager for coding agents.
Install
uvx mcp-server-matrixpip install mcp-server-matrixThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (16)
create_roomCreate a new room (with optional invites)
Parameters not published.
get_direct_messagesList DM conversations with unread status
Parameters not published.
get_messages_by_dateGet messages filtered by date range
Parameters not published.
get_notification_countsUnread and mention counts per room
Parameters not published.
get_room_infoRoom details — name, topic, members, encryption status
Parameters not published.
get_room_membersList joined members with display names and avatars
Parameters not published.
get_user_profileUser profile — display name, avatar
Parameters not published.
invite_userInvite a user to a room
Parameters not published.
join_roomJoin a room by ID or alias
Parameters not published.
leave_roomLeave a room
Parameters not published.
Show all 16 tools
list_roomsList all joined rooms
Parameters not published.
read_messagesRead recent messages (with pagination)
Parameters not published.
resolve_aliasResolve `#alias:server` to a room ID
Parameters not published.
send_direct_messageSend a DM (auto-creates room if needed)
Parameters not published.
send_messageSend a message (text, HTML, or Markdown) with optional reply
Parameters not published.
send_reactionReact to a message with an emoji
Parameters not published.
Ask AI
Ask AI about mcp-server-matrix
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
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
Links
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.