Element

You deploy an MCP server that bridges Claude with your Matrix account. Once configured, you can list Matrix rooms, read messages, search content, and view room details from within Claude conversations, enabling powerful context-aware interactions with your Matrix data.

How to use

Set up your MCP server as a local, stdio-based service and connect Claude to it. With the server running, you can ask Claude to list your Matrix rooms, fetch messages from specific rooms, search messages by content, and retrieve detailed information about rooms. Use the available tools to build conversational workflows that explore your Matrix history without exposing sensitive actions like sending messages.

Typical usage patterns include asking Claude to show all joined rooms, request recent messages from a room, search for terms across chats, or inquire about room metadata. The server only performs read operations and never sends messages, ensuring your Matrix data remains read-only within this MCP setup.

How to install

Prerequisites you must have before installation: Node.js 18+ installed. A Matrix account (for example on matrix.org or Element). Your Matrix Access Token.

Install and build the MCP server locally with the following steps.

# Clone the repository
git clone https://github.com/rosquillas/matrix-mcp-server.git
cd matrix-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Configure the MCP server to connect to your Matrix homeserver and provide your access token. The server runs in stdio mode by default, consuming environment variables for its setup.

Environment variables you need to set:

# Your Matrix homeserver (default: https://matrix.org)
MATRIX_HOMESERVER=https://matrix.org

# Your access token (REQUIRED)
MATRIX_ACCESS_TOKEN=your_token_here

# Transport type: 'stdio' or 'http' (default: stdio)
TRANSPORT=stdio

# Port for HTTP mode (default: 3000)
PORT=3000

Security

The access token is provided as an environment variable and is not stored in code. The server operates with read-only permissions and only communicates with your configured homeserver.

Troubleshooting

If you see an error stating that MATRIX_ACCESS_TOKEN is required, ensure you set the environment variable with your token.

If you encounter a Matrix API error 401, your token may be expired or invalid. Generate a new one from Element and update the environment variable.

If you see a Matrix API error 403, you do not have permissions to access that room.

Available tools

matrix_list_rooms

List all rooms you've joined. Accepts an optional limit to cap how many rooms are returned.

matrix_get_messages

Fetch messages from a specific room. Accepts room_id, limit, and direction to navigate older or newer messages.

matrix_search_messages

Search messages by content across rooms. Accepts query, optional room_id, and limit for result count.

matrix_get_room_info

Retrieve detailed information about a specific room using its room_id.