Skip to main content
Glama
deenesjakoruzh
sagelabs-dev

matrix-mcp-server

by sagelabs-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

@guan-tends/matrix-mcp-server

npm version License: MIT Node.js Version

一个独立的 MCP（Model Context Protocol）工具服务器，将 Matrix 聊天操作暴露为可调用的工具。任何兼容 MCP 的客户端——AI 智能体、自动化流水线、开发者工具——都可以使用这些工具发送消息、管理房间、解析名称，并与 Matrix 协议交互。

基于 @vector-im/matrix-bot-sdk 构建，支持完整的 E2EE（端到端加密）。

特性

  • 15 个 MCP 工具——消息、房间管理、用户管理和智能 ID 解析

  • E2EE 支持——通过 Rust 加密后端实现完整的 Megolm 加密

  • 人性化的名称解析——通过名称而非不透明的 ID 来引用房间和用户

  • 别名系统——教服务器自定义快捷方式（例如 "eng" → "!abc123:matrix.org"）

  • 独立 HTTP 服务器——独立运行，可通过 HTTP 连接任何 MCP 客户端

  • 零 cron、零 LLM——纯粹的工具服务器。调度和智能都位于智能体层。

Related MCP server: ottoauthMCP

安装

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

要求

  • Node.js >= 22.0.0

  • 一个带有访问令牌的 Matrix 账户

快速开始

1. 克隆并配置

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

使用你的 Matrix 凭据编辑 config.json5：

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

2. 运行

npm start

服务器监听 http://0.0.0.0:3456，并通过 HTTP 接受 MCP 协议请求。

3. 连接你的 MCP 客户端

将任何兼容 MCP 的客户端指向该服务器：

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

或者与 @guan-tends/mcp-ai 聚合器配合使用，以实现多服务器工具组合。

配置

基于文件

编辑 config.json5（所有选项参见 config.example.json5）。

环境变量

所有配置值都可以通过环境变量设置（优先级最高）：

变量

配置键

MATRIX_MCP_HOMESERVER_URL

homeserverUrl

MATRIX_MCP_ACCESS_TOKEN

accessToken

MATRIX_MCP_PORT

port

MATRIX_MCP_HOST

host

MATRIX_MCP_SERVER_NAME

serverName

MATRIX_MCP_STORE_PATH

storePath

MATRIX_MCP_CRYPTO_PATH

cryptoPath

工具 (15)

消息

工具

描述

send_message

向房间发送文本（按 ID 或解析后的名称）

send_html_message

发送 HTML 格式的消息

send_reaction

用表情符号对消息做出反应

send_dm

发送私信（必要时创建加密私信）

房间管理

工具

描述

join_room

按 ID 或别名加入房间

leave_room

离开房间

get_joined_rooms

列出所有已加入的房间

get_room_messages

获取房间的最近消息

用户管理

工具

描述

get_presence

获取用户的在线状态

invite_user

邀请用户加入房间

kick_user

将用户移出房间

ID 解析

工具

描述

set_room_alias

教服务器一个房间别名（例如 "eng" → "!abc:matrix.org"）

set_user_alias

教服务器一个用户别名（例如 "alice" → "@alice:matrix.org"）

resolve_room

将房间名称解析为其 Matrix ID，并给出置信度分数

resolve_user

将用户名称解析为其 Matrix ID，并给出置信度分数

解析策略

解析器采用混合方法并进行置信度评分：

  1. 用户别名（置信度：1.0）——用户定义的映射

  2. 精确匹配（置信度：0.9）——精确的显示名称或规范别名

  3. 部分匹配（置信度：0.7）——名称的部分匹配

  4. 歧义（置信度：0.5）——多个匹配，返回候选结果

架构

                    ┌─────────────────────────┐
                    │      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：index.js 负责装配所有依赖。没有模块会导入其他模块的依赖。每个模块都可以独立测试。

设计决策

  1. 组合根 IoC——index.js 负责装配所有依赖。模块之间不交叉导入。

  2. 极简 AliasStore——房间/用户别名管理仅需 4 个方法。

  3. 简单的 JSON 持久化——persist.js 负责加载/保存。两个数据文件。

  4. withErrorHandling 包装器——消除了每个工具中重复的 try/catch。

  5. 无 cron、无 LLM、无 bot——纯粹的 MCP 工具服务器。智能体自行处理调度。

测试

# All tests (unit + E2E)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

65 个测试，分布在 6 个文件中（5 个单元测试，1 个 E2E 测试）。

项目结构

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

赞助商

如果这个项目对你有用，请考虑支持它的开发：

  • GitHub Sponsors

  • Solana: Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6

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

  • XRP Ledger: r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG

许可证

MIT © 2026 Guan

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • ottoauthMCP

    Clamepending
    F
    license
    A
    quality
    D
    maintenance
    Standalone MCP server that proxies tool calls to Ottoauth HTTP endpoints, enabling account creation and dynamic service interaction.
    7
    -

  • rocketchat-mcp

    SufiSR
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for Rocket.Chat, enabling AI agents to interact with Rocket.Chat workspaces via tools like listing users, sending messages, and managing channels.
    2
    -

  • matrix-mcp

    cosmic-fire-eng
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Matrix that lets Claude list rooms, search/read messages, send messages and files, react, create rooms, and invite users, with multi-homeserver support and safe-by-default writes; no end-to-end encryption.
    MIT