matrix-mcp-server

Matrix MCP Server

Matrix ホームサーバーの機能に安全にアクセスできる、包括的な Model Context Protocol（MCP）サーバーです。TypeScript で構築されており、標準化されたインターフェースを通じて、MCP クライアントが Matrix のルーム、メッセージ、ユーザーなどを操作できます。

Features

• 🔐 トークン交換に対応した OAuth 2.0 認証
• 📱 機能別の階層に整理された 15 個の Matrix ツール
• 🏠 エンドポイントを設定可能なマルチホームサーバー対応
• 🔄 エフェメラルクライアント管理によるリアルタイム操作
• 🚀 包括的なエラー処理を備えた本番環境対応
• 📊 Matrix の詳細データを含む豊富なレスポンス

Quick Start

Prerequisites

• Node.js 20+ と npm
• Matrix ホームサーバーへのアクセス（Synapse、Dendrite など）
• MCP クライアント（Claude Desktop、MCP 拡張機能を備えた VS Code など）

Installation

# Clone the repository
git clone <repository-url>
cd matrix-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start the server
npm start

Development Mode

# Start with hot reload (OAuth disabled for easier testing)
npm run dev

# Or start with OAuth enabled
ENABLE_OAUTH=true npm run dev

Available Tools

📖 Tier 0: 読み取り専用ツール

ルームツール

• list-joined-rooms - ユーザーが参加しているすべてのルームを取得します

  • パラメーターは不要です
  • ルーム名、ID、メンバー数を返します

• get-room-info - ルームの詳細情報を取得します

  • roomId（string）：Matrix ルーム ID（例：!roomid:domain.com）
  • 名前、トピック、設定、作成者、メンバー数を返します

• get-room-members - ルーム内のすべてのメンバーを一覧表示します

  • roomId（string）：Matrix ルーム ID
  • 参加中のメンバーの表示名とユーザー ID を返します

メッセージツール

• get-room-messages - ルームの最近のメッセージを取得します

  • roomId（string）：Matrix ルーム ID
  • limit（number、デフォルト：20）：取得するメッセージの最大数
  • テキストや画像を含む、書式設定済みのメッセージ内容を返します

• get-messages-by-date - 日付範囲でメッセージを絞り込みます

  • roomId（string）：Matrix ルーム ID
  • startDate（string）：ISO 8601 形式（例：2024-01-01T00:00:00Z）
  • endDate（string）：ISO 8601 形式
  • 指定した期間内のメッセージを返します

• identify-active-users - メッセージ数を基に、最もアクティブなユーザーを特定します

  • roomId（string）：Matrix ルーム ID
  • limit（number、デフォルト：10）：返すユーザーの最大数
  • メッセージのアクティビティ順にユーザーを返します

ユーザーツール

• get-user-profile - 任意のユーザーのプロフィール情報を取得します

  • targetUserId（string）：対象ユーザーの Matrix ID（例：@user:domain.com）
  • 表示名、アバター、プレゼンス、共通のルームを返します

• get-my-profile - 自分のプロフィール情報を取得します

  • パラメーターは不要です
  • 自分のプロフィール、デバイス情報、ルームの統計情報を返します

• get-all-users - クライアントが把握しているすべてのユーザーを一覧表示します

  • パラメーターは不要です
  • クライアントのキャッシュから表示名とユーザー ID を返します

検索ツール

• search-public-rooms - 参加可能な公開ルームを検索します
  • searchTerm（string、任意）：名前またはトピックで絞り込みます
  • server（string、任意）：検索対象の特定のサーバー
  • limit（number、デフォルト：20）：返すルームの最大数
  • ルームの詳細、トピック、メンバー数を返します

通知ツール

• get-notification-counts - 未読メッセージとメンションを確認します

  • roomFilter（string、任意）：確認対象の特定のルーム ID
  • 未読件数、メンション、最近のアクティビティを返します

• get-direct-messages - すべてのダイレクトメッセージの会話を一覧表示します

  • includeEmpty（boolean、デフォルト：false）：最近のメッセージがない DM も含めます
  • DM の相手、最後のメッセージ、未読状況を返します

✏️ Tier 1: アクションツール

メッセージングツール

• send-message - ルームにメッセージを送信します

  • roomId（string）：Matrix ルーム ID
  • message（string）：メッセージの内容
  • messageType（enum: "text" | "html" | "emote", default: "text"）：メッセージの書式
  • replyToEventId（string, optional）：返信先のイベント ID
  • プレーンテキスト、HTML 書式、エモートアクションに対応しています

• send-direct-message - ユーザーにプライベートメッセージを送信します

  • targetUserId（string）：対象ユーザーの Matrix ID
  • message（string）：メッセージの内容
  • 必要に応じて DM ルームを自動的に作成します

ルーム管理ツール

• create-room - 新しい Matrix ルームを作成します

  • roomName（string）：新しいルームの名前
  • isPrivate（boolean, default: false）：ルームのプライバシー設定
  • topic（string, optional）：ルームのトピック／説明
  • inviteUsers（array, optional）：最初に招待するユーザー ID
  • roomAlias（string, optional）：人が読みやすいルームエイリアス
  • 適切なセキュリティ設定でルームを作成します

• join-room - ID またはエイリアスでルームに参加します

  • roomIdOrAlias（string）：参加するルームの ID またはエイリアス
  • 招待されたルームと公開ルームの両方に対応しています

• leave-room - Matrix ルームから退出します

  • roomId（string）：退出するルームの ID
  • reason（string, optional）：退出理由
  • 任意で理由を指定して、ルームから適切に退出します

• invite-user - ユーザーをルームに招待します

  • roomId（string）：ユーザーを招待するルーム
  • targetUserId（string）：招待するユーザー ID
  • ルームの権限と権限レベルに従います

ルーム管理者ツール

• set-room-name - ルームの表示名を更新します

  • roomId（string）：変更するルーム
  • roomName（string）：新しいルーム名
  • 適切なルーム権限が必要です

• set-room-topic - ルームのトピック／説明を更新します

  • roomId（string）：変更するルーム
  • topic（string）：新しいルームのトピック
  • 適切なルーム権限が必要です

認証と設定

認証モード

サーバーは、次の 2 つの認証モードに対応しています。

OAuth モード（ENABLE_OAUTH=true）

• ID プロバイダーとの完全な OAuth 2.0 統合
• Matrix ホームサーバー認証のトークン交換に対応
• 適切なトークン管理による安全なマルチユーザーアクセス
• 本番環境へのデプロイに推奨

開発モード（ENABLE_OAUTH=false）

• OAuth 認証なしで直接アクセス
• Matrix アクセストークンをヘッダーとして指定する必要があります
• テストと開発向けの簡易セットアップ
• 本番環境での使用は推奨されません

環境変数

設定を記述した .env ファイルを作成します。

# Core Configuration
PORT=3000
ENABLE_OAUTH=true                    # Enable OAuth authentication
ENABLE_TOKEN_EXCHANGE=true           # Exchange OAuth tokens for Matrix tokens
CORS_ALLOWED_ORIGINS=""              # Comma-separated allowed origins (empty = allow all)

# HTTPS Configuration (optional)
ENABLE_HTTPS=false
SSL_KEY_PATH="/path/to/private.key"
SSL_CERT_PATH="/path/to/certificate.crt"

# Identity Provider (OAuth mode)
IDP_ISSUER_URL="https://keycloak.example.com/realms/matrix"
IDP_AUTHORIZATION_URL="https://keycloak.example.com/realms/matrix/protocol/openid-connect/auth"
IDP_TOKEN_URL="https://keycloak.example.com/realms/matrix/protocol/openid-connect/token"
OAUTH_CALLBACK_URL="http://localhost:3000/callback"

# Matrix Configuration
MATRIX_HOMESERVER_URL="https://matrix.example.com"
MATRIX_DOMAIN="matrix.example.com"
MATRIX_CLIENT_ID="your-matrix-client-id"
MATRIX_CLIENT_SECRET="your-matrix-client-secret"

クライアント統合

Claude Code

MATRIX_ACCESS_TOKEN ヘッダーは任意です。トークン交換が機能している場合は、このヘッダーを削除してください。MATRIX_MCP_TOKEN は MCP Inspector から取得します。

claude mcp add --transport http matrix-server http://localhost:3000/mcp -H "matrix_user_id:  @user1:matrix.example.com" -H "matrix_homeserver_url: https://localhost:8008" -H "matrix_access_token: ${MATRIX_ACCESS_TOKEN}" -H "Authorization: Bearer ${MATRIX_MCP_TOKEN}"

VS Code

matrix_access_token ヘッダーは任意です。トークン交換が機能している場合は、このヘッダーを削除してください。

mcp.json 内：

{
  "servers": {
    "matrix-mcp": {
      "url": "http://localhost:3000/mcp",
      "type": "http",
      "headers": {
        "matrix_access_token": "${input:matrix-access-token}",
        "matrix_user_id": "@<your-matrix-username>:<your-homeserver-domain>",
        "matrix_homeserver_url": "<your-homeserver-url>"
      }
    }
  },
  "inputs": [
    {
      "id": "matrix-access-token",
      "type": "promptString",
      "description": "Your OAuth access token"
    }
  ]
}

MCP Inspector でのテスト

# Start the server
npm run dev

# In another terminal, run the inspector
npx @modelcontextprotocol/inspector

http://localhost:3000/mcp に接続し、認証して利用可能なすべてのツールをテストします。

開発

利用可能なスクリプト

npm run build      # Build TypeScript to dist/
npm run dev        # Development server with hot reload
npm run start      # Production server
npm run lint       # Run ESLint
npm run test       # Run tests

プロジェクト構成

src/
├── http-server.ts           # Main HTTP server entry point
├── server.ts               # MCP server configuration
├── tools/                  # Tool implementations
│   ├── tier0/             # Read-only tools
│   │   ├── rooms.ts       # Room information tools
│   │   ├── messages.ts    # Message retrieval tools
│   │   ├── users.ts       # User profile tools
│   │   ├── search.ts      # Room search tools
│   │   └── notifications.ts # Notification tools
│   └── tier1/             # Action tools
│       ├── messaging.ts   # Message sending tools
│       ├── room-management.ts # Room lifecycle tools
│       └── room-admin.ts  # Room administration tools
├── matrix/                # Matrix client management
├── utils/                 # Helper utilities
└── types/                 # TypeScript type definitions

セキュリティに関する考慮事項

• 🔐 トークン管理：すべての Matrix クライアントは一時的に作成され、操作後にクリーンアップされます
• 🛡️ OAuth 統合：OAuth プロキシを介して Matrix トークンが直接公開されるのを防ぎます
• 🔍 権限チェック：Matrix ルームの権限レベルとアクセス権限に従います
• 🚫 入力検証：Zod スキーマを使用してパラメーターを包括的に検証します
• 🌐 CORS サポート：ウェブクライアント向けにオリジン制限を設定できます

アーキテクチャ

サーバーは3層アーキテクチャを実装しています。

1. HTTP 層（http-server.ts）：OAuth 統合を備えた Express サーバー
2. MCP 層（server.ts）：ツールの登録とリクエストのルーティング
3. Matrix 層（tools/）：Matrix ホームサーバーとの通信

各ツールは一時的な Matrix クライアントを作成し、設定された方式で認証を行って要求された操作を実行した後、自動的にクリーンアップします。

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。