Element MCP Server

An MCP (Model Context Protocol) server that connects Claude with Element. Read rooms, messages, and search content in your Matrix conversations.

🌐 También disponible en español más abajo / Spanish version below

What is this?

This server acts as a "bridge" between Claude and your Matrix account. Once configured, Claude can:

List your Matrix rooms
Read messages from any room
Search messages by content
View detailed room information

Prerequisites

Node.js 18+ installed
A Matrix account (e.g., on matrix.org or Element)
Your Matrix Access Token

Getting your Access Token

From Element Web/Desktop:

Open Element and go to Settings (gear icon)
Go to Help & About
In the advanced section, find Access Token
Copy the token (starts with something like syt_... or MDAxO...)

⚠️ Important: Your access token is like a password. Don't share it publicly.

Installation

# 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

Environment Variables

# 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

Usage

stdio mode (recommended for Claude Desktop)

MATRIX_ACCESS_TOKEN=your_token npm start

HTTP mode (for remote use)

TRANSPORT=http MATRIX_ACCESS_TOKEN=your_token npm start

Claude Desktop Configuration

Add this to your Claude Desktop config file:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "matrix": {
      "command": "node",
      "args": ["/path/to/matrix-mcp-server/dist/index.js"],
      "env": {
        "MATRIX_HOMESERVER": "https://matrix.org",
        "MATRIX_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Available Tools

`matrix_list_rooms`

List all rooms you've joined.

Parameters:

limit (optional): Maximum number of rooms (1-100, default: 20)

`matrix_get_messages`

Get messages from a specific room.

Parameters:

room_id (required): Room ID (e.g., !abc123:matrix.org)
limit (optional): Number of messages (1-100, default: 50)
direction (optional): 'b' for older, 'f' for newer

`matrix_search_messages`

Search messages by content.

Parameters:

query (required): Text to search
room_id (optional): Limit to a specific room
limit (optional): Max results (1-50, default: 10)

`matrix_get_room_info`

Get detailed room information.

Parameters:

room_id (required): Room ID

Example Usage

Once configured, you can tell Claude:

"Show me my Matrix rooms"

"What was discussed yesterday in the development room?"

"Search for messages about 'deployment' in my chats"

Security

Access token is passed as environment variable, never stored in code
Only read operations (cannot send messages)
Server only communicates with your configured homeserver

Troubleshooting

"MATRIX_ACCESS_TOKEN environment variable is required"

Make sure to set the environment variable with your token.

"Matrix API error (401)"

Your token expired or is invalid. Generate a new one from Element.

"Matrix API error (403)"

You don't have permissions to access that room.

Versión en Español

¿Qué es esto?

Este servidor actúa como un "puente" entre Claude y tu cuenta de Matrix. Una vez configurado, Claude puede:

Ver tus salas de Matrix
Leer mensajes de cualquier sala
Buscar mensajes por contenido
Ver información detallada de las salas

Requisitos Previos

Node.js 18+ instalado
Una cuenta de Matrix (por ejemplo, en matrix.org o Element)
Tu Access Token de Matrix

Obtener tu Access Token

Desde Element Web/Desktop:

Abre Element y ve a Configuración (ícono de engrane)
Ve a Ayuda y Sobre (Help & About)
En la sección avanzada, encontrarás Access Token
Copia el token (empieza con algo como syt_... o MDAxO...)

⚠️ Importante: Tu access token es como una contraseña. No lo compartas públicamente.

Instalación

# Clona el repositorio
git clone https://github.com/rosquillas/matrix-mcp-server.git
cd matrix-mcp-server

# Instala dependencias
npm install

# Compila el proyecto
npm run build

Configuración con Claude Desktop

Agrega esto a tu archivo de configuración:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "matrix": {
      "command": "node",
      "args": ["/ruta/a/matrix-mcp-server/dist/index.js"],
      "env": {
        "MATRIX_HOMESERVER": "https://matrix.org",
        "MATRIX_ACCESS_TOKEN": "tu_token_aqui"
      }
    }
  }
}

License

MIT