# Element MCP Server
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
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
```bash
# 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
```bash
# 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)
```bash
MATRIX_ACCESS_TOKEN=your_token npm start
```
### HTTP mode (for remote use)
```bash
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`
```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
```bash
# 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`
```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
