License: MIT Node.js MCP

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:

1. Open Element and go to Settings (gear icon)
2. Go to Help & About
3. In the advanced section, find Access Token
4. 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:

1. Abre Element y ve a Configuración (ícono de engrane)
2. Ve a Ayuda y Sobre (Help & About)
3. En la sección avanzada, encontrarás Access Token
4. 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