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

Matrix のチャット操作を呼び出し可能なツールとして公開する、スタンドアロンの MCP（Model Context Protocol）ツールサーバーです。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

config.json5 を 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. 実行

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

ダイレクトメッセージを送信（必要に応じて暗号化 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
            └──────────────────┘

Composition-Root IoC: index.js がすべての依存関係を配線します。どのモジュールも他のモジュールの依存関係をインポートしません。各モジュールは独立してテスト可能です。

設計上の決定

  1. Composition-Root IoC — index.js がすべての依存関係を配線します。モジュールは相互インポートしません。

  2. 最小限の AliasStore — ルーム/ユーザーエイリアス管理に必要なメソッドはわずか 4 つです。

  3. シンプルな JSON 永続化 — persist.js がロード/セーブを処理します。データファイルは 2 つです。

  4. withErrorHandling ラッパー — 各ツールで繰り返される try/catch を DRY 化します。

  5. cron なし、LLM なし、ボットなし — 純粋な MCP ツールサーバー。エージェントが自身のスケジューリングを処理します。

テスト

# All tests (unit + E2E)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

65 件のテスト を 6 ファイル（単体テスト 5、E2E 1）で実施。

プロジェクト構成

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