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_...orMDAxO...)
⚠️ 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 searchroom_id(optional): Limit to a specific roomlimit(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_...oMDAxO...)
⚠️ 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