# Element MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](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