@guan-tends/matrix-mcp-server

Ein eigenständiger MCP-Toolserver (Model Context Protocol), der Matrix-Chat-Operationen als aufrufbare Tools bereitstellt. Jeder MCP-kompatible Client – KI-Agenten, Automatisierungspipelines, Entwicklerwerkzeuge – kann diese Tools nutzen, um Nachrichten zu senden, Räume zu verwalten, Namen aufzulösen und mit dem Matrix-Protokoll zu interagieren.

Basiert auf @vector-im/matrix-bot-sdk mit vollständiger E2EE-Unterstützung (Ende-zu-Ende-Verschlüsselung).

Funktionen

• 15 MCP-Tools – Nachrichtenübermittlung, Raumverwaltung, Benutzerverwaltung und intelligente ID-Auflösung

• E2EE-Unterstützung – Vollständige Megolm-Verschlüsselung über das Rust-Krypto-Backend

• Benutzerfreundliche Namensauflösung – Räume und Benutzer per Name referenzieren, nicht über undurchsichtige IDs

• Alias-System – Dem Server benutzerdefinierte Verknüpfungen beibringen (z. B. "eng" → "!abc123:matrix.org")

• Eigenständiger HTTP-Server – Läuft unabhängig, verbinden Sie jeden MCP-Client über HTTP

• Kein Cron, kein LLM – Reiner Toolserver. Planung und Intelligenz liegen in der Agentenebene

Related MCP server: ottoauthMCP

Installation

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

Voraussetzungen

• Node.js >= 22.0.0

• Ein Matrix-Konto mit einem Zugriffstoken

Schnellstart

1. Klonen und konfigurieren

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

Bearbeiten Sie config.json5 mit Ihren Matrix-Anmeldedaten:

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

2. Ausführen

npm start

Der Server lauscht auf http://0.0.0.0:3456 und akzeptiert MCP-Protokollanfragen über HTTP.

3. MCP-Client verbinden

Richten Sie einen beliebigen MCP-kompatiblen Client auf den Server aus:

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

Oder verwenden Sie den @guan-tends/mcp-ai-Aggregator für die Multi-Server-Toolkomposition.

Konfiguration

Dateibasiert

Bearbeiten Sie config.json5 (siehe config.example.json5 für alle Optionen).

Umgebungsvariablen

Alle Konfigurationswerte können über Umgebungsvariablen gesetzt werden (höchste Priorität):

Tools (15)

Nachrichtenübermittlung

Raumverwaltung

Benutzerverwaltung

ID-Auflösung

Auflösungsstrategie

Der Resolver verwendet einen hybriden Ansatz mit Konfidenzbewertung:

1. Benutzer-Aliase (Konfidenz: 1.0) – Benutzerdefinierte Zuordnungen

2. Exakte Übereinstimmung (Konfidenz: 0.9) – Exakter Anzeigename oder kanonischer Alias

3. Teilweise Übereinstimmung (Konfidenz: 0.7) – Teilweise Namensübereinstimmung

4. Mehrdeutigkeit (Konfidenz: 0.5) – Mehrere Übereinstimmungen, gibt Kandidaten zurück

Architektur

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

Composition-Root-IoC: index.js verdrahtet alle Abhängigkeiten. Kein Modul importiert die Abhängigkeiten eines anderen. Jedes Modul ist unabhängig testbar.

Designentscheidungen

1. Composition-Root-IoC – index.js verdrahtet alle Abhängigkeiten. Module importieren sich nicht gegenseitig.

2. Minimaler AliasStore – Nur 4 Methoden für die Raum-/Benutzer-Aliasverwaltung erforderlich.

3. Einfache JSON-Persistenz – persist.js übernimmt Laden/Speichern. Zwei Datendateien.

4. withErrorHandling-Wrapper – DRY-Prinzip für das wiederholte try/catch in jedem Tool.

5. Kein Cron, kein LLM, kein Bot – Reiner MCP-Toolserver. Agenten übernehmen ihre eigene Planung.

Testen

# All tests (unit + E2E)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

65 Tests in 6 Dateien (5 Unit, 1 E2E).

Projektstruktur

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

Sponsoren

Wenn dieses Projekt für Sie nützlich ist, erwägen Sie bitte, seine Entwicklung zu unterstützen:

• GitHub Sponsors

• Solana: Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6

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

• XRP Ledger: r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG

Lizenz

MIT © 2026 Guan