@guan-tends/matrix-mcp-server

A standalone MCP (Model Context Protocol) tool server that exposes Matrix chat operations as callable tools. Any MCP-compatible client — AI agents, automation pipelines, developer tools — can use these tools to send messages, manage rooms, resolve names, and interact with the Matrix protocol.

Built on @vector-im/matrix-bot-sdk with full E2EE (end-to-end encryption) support.

Features

• 15 MCP tools — messaging, room management, user management, and intelligent ID resolution

• E2EE support — full Megolm encryption via Rust crypto backend

• Human-friendly name resolution — refer to rooms and users by name, not opaque IDs

• Alias system — teach the server custom shortcuts (e.g., "eng" → "!abc123:matrix.org")

• Standalone HTTP server — runs independently, connect any MCP client via HTTP

• Zero-cron, zero-LLM — pure tool server. Scheduling and intelligence live in the agent layer

Related MCP server: ottoauthMCP

Install

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

Requirements

• Node.js >= 22.0.0

• A Matrix account with an access token

Quick Start

1. Clone and configure

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

Edit config.json5 with your Matrix credentials:

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

2. Run

npm start

The server listens on http://0.0.0.0:3456 and accepts MCP protocol requests over HTTP.

3. Connect your MCP client

Point any MCP-compatible client at the server:

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

Or use with @guan-tends/mcp-ai aggregator for multi-server tool composition.

Configuration

File-based

Edit config.json5 (see config.example.json5 for all options).

Environment variables

All config values can be set via environment variables (highest precedence):

Tools (15)

Messaging

Room Management

User Management

ID Resolution

Resolution Strategy

The resolver uses a hybrid approach with confidence scoring:

1. User aliases (confidence: 1.0) — User-defined mappings

2. Exact match (confidence: 0.9) — Exact display name or canonical alias

3. Partial match (confidence: 0.7) — Partial name match

4. Ambiguity (confidence: 0.5) — Multiple matches, returns candidates

Architecture

                    ┌─────────────────────────┐
                    │      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 wires all dependencies. No module imports another's deps. Each module is independently testable.

Design Decisions

1. Composition-Root IoC — index.js wires all dependencies. Modules don't cross-import.

2. Minimal AliasStore — Only 4 methods needed for room/user alias management.

3. Simple JSON persistence — persist.js handles load/save. Two data files.

4. withErrorHandling wrapper — DRYs the repeated try/catch in every tool.

5. No cron, no LLM, no bot — Pure MCP tool server. Agents handle their own scheduling.

Testing

# All tests (unit + E2E)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

65 tests across 6 files (5 unit, 1 E2E).

Project Structure

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

Sponsors

If this project is useful to you, consider supporting its development:

• GitHub Sponsors

• Solana: Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6

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

• XRP Ledger: r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG

License

MIT © 2026 Guan