mcp-server-matrix

README на русском

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

mcp-server-matrix

mcp-server-matrix

Features

Installation

Configuration

Usage

Claude Desktop

Claude Code

OpenClaw

Direct (stdio)

Examples

Supported Homeservers

Requirements

License

Links

Latest Blog Posts

MCP directory API