@guan-tends/matrix-mcp-server

Un servidor de herramientas MCP (Model Context Protocol) independiente que expone operaciones de chat de Matrix como herramientas invocables. Cualquier cliente compatible con MCP — agentes de IA, pipelines de automatización, herramientas de desarrollo — puede usar estas herramientas para enviar mensajes, gestionar salas, resolver nombres e interactuar con el protocolo Matrix.

Construido sobre @vector-im/matrix-bot-sdk con soporte completo de E2EE (cifrado de extremo a extremo).

Características

• 15 herramientas MCP — mensajería, gestión de salas, gestión de usuarios y resolución inteligente de IDs

• Soporte E2EE — cifrado Megolm completo mediante backend criptográfico Rust

• Resolución de nombres amigable — refiérete a salas y usuarios por nombre, no por IDs opacos

• Sistema de alias — enseña al servidor accesos directos personalizados (p. ej., "eng" → "!abc123:matrix.org")

• Servidor HTTP independiente — se ejecuta de forma autónoma, conecta cualquier cliente MCP vía HTTP

• Cero cron, cero LLM — servidor de herramientas puro. La programación y la inteligencia viven en la capa del agente

Related MCP server: ottoauthMCP

Instalación

npm install @guan-tends/matrix-mcp-server

Requisitos

• Node.js >= 22.0.0

• Una cuenta de Matrix con un token de acceso

Inicio rápido

1. Clona y configura

git clone https://github.com/guan-tends/matrix-mcp-server.git
cd matrix-mcp-server
npm install
cp config.example.json5 config.json5

Edita config.json5 con tus credenciales de Matrix:

{
  homeserverUrl: "https://matrix.org",
  accessToken: "syt_...",
  serverName: "matrix.org",
  port: 3456,
  host: "0.0.0.0",
  storePath: "./data/store.json",
  cryptoPath: "./data/crypto",
}

2. Ejecuta

npm start

El servidor escucha en http://0.0.0.0:3456 y acepta solicitudes del protocolo MCP sobre HTTP.

3. Conecta tu cliente MCP

Apunta cualquier cliente compatible con MCP al servidor:

{
  "mcpServers": {
    "matrix": {
      "url": "http://localhost:3456"
    }
  }
}

O úsalo con el agregador @guan-tends/mcp-ai para la composición de herramientas de múltiples servidores.

Configuración

Basado en archivos

Edita config.json5 (consulta config.example.json5 para todas las opciones).

Variables de entorno

Todos los valores de configuración se pueden establecer mediante variables de entorno (máxima precedencia):

Herramientas (15)

Mensajería

Gestión de salas

Gestión de usuarios

Resolución de IDs

Estrategia de resolución

El resolvedor utiliza un enfoque híbrido con puntuación de confianza:

1. Alias de usuario (confianza: 1.0) — Mapeos definidos por el usuario

2. Coincidencia exacta (confianza: 0.9) — Nombre para mostrar exacto o alias canónico

3. Coincidencia parcial (confianza: 0.7) — Coincidencia parcial del nombre

4. Ambigüedad (confianza: 0.5) — Múltiples coincidencias, devuelve candidatos

Arquitectura

                    ┌─────────────────────────┐
                    │      index.js            │
                    │   (composition root)     │
                    └──────────┬──────────────┘
                               │ wires
              ┌────────────────┼────────────────┐
              ▼                ▼                 ▼
     ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
     │ MatrixClient │  │  AliasStore  │  │ McpDataStore │
     │ (bot-sdk)    │  │ (aliases)    │  │ (DM cache)   │
     └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
            │                 │                  │
            └────────┬────────┘                  │
                     ▼                           │
            ┌──────────────────┐                 │
            │ MatrixIdResolver  │◄────────────────┘
            └────────┬─────────┘
                     │
                     ▼
            ┌──────────────────┐
            │   mcp-server.js   │── MCP SDK SimpleServer
            │   (15 tools)      │── HTTP transport
            └──────────────────┘

IoC de raíz de composición: index.js conecta todas las dependencias. Ningún módulo importa las dependencias de otro. Cada módulo es comprobable de forma independiente.

Decisiones de diseño

1. IoC de raíz de composición — index.js conecta todas las dependencias. Los módulos no se importan entre sí.

2. AliasStore mínimo — Solo se necesitan 4 métodos para la gestión de alias de salas/usuarios.

3. Persistencia JSON simple — persist.js gestiona la carga/guardado. Dos archivos de datos.

4. Envoltorio withErrorHandling — Evita la repetición del try/catch en cada herramienta.

5. Sin cron, sin LLM, sin bot — Servidor de herramientas MCP puro. Los agentes gestionan su propia programación.

Pruebas

# All tests (unit + E2E)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

65 pruebas en 6 archivos (5 unitarias, 1 E2E).

Estructura del proyecto

src/
├── index.js              — Composition root: config → Matrix client → wire → start
├── mcp-server.js          — 15 MCP tools + helpers (withErrorHandling, resolveRoomInput, etc.)
├── matrix-id-resolver.js  — Room/user name → Matrix ID resolution
├── alias-store.js         — Minimal per-user alias storage
├── mcp-data-store.js      — DM room ID cache
└── persist.js             — Simple JSON load/save utility

__tests__/
├── unit/                  — Unit tests (alias-store, mcp-data-store, resolver, mcp-server, persist)
├── e2e/                   — E2E test (full server start → MCP client → tool calls)
├── mocks/                 — Mock MatrixClient for testing
└── vitest.config.js

Patrocinadores

Si este proyecto te resulta útil, considera apoyar su desarrollo:

• GitHub Sponsors

• Solana: Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6

• EVM (Ethereum / Base / Arbitrum / Optimism / Polygon): 0x2733ff7c865C56d565a99BE1DC11B81cc76850A5

• XRP Ledger: r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG

Licencia

MIT © 2026 Guan