AI导哈

Matrix MCP服务器

一个全面的Model Context Protocol (MCP)服务器，提供对Matrix homeserver功能的安全访问，支持通过标准化接口与Matrix房间、消息、用户等进行交互。

  • by mjknowles
  • TypeScript
  • 本地部署
  • 57 星标
  • 更新于
在 GitHub 查看 mjknowles/matrix-mcp-server

使用说明

矩阵MCP服务器

全面 模型上下文协议（MCP）服务器 它提供对Matrix主服务器功能的安全访问。该服务器使用TypeScript构建，使MCP客户端能够通过标准化的接口与Matrix房间、消息、用户等进行交互。

特性

  • 🔐 OAuth 2.0身份验证 支持代币兑换
  • 📱 15个矩阵工具 按功能层组织
  • 🏠 多家庭服务器支持 具有可配置的端点
  • 🔄 实时操作 具有临时客户端管理功能
  • 🚀 生产就绪 具有全面的错误处理功能
  • 📊 丰富的响应 包含详细的Matrix数据

快速开始

先决条件

  • Node.js 20+ 和npm
  • 矩阵主服务器 访问（Synapse、树突等）
  • MCP客户端 （克劳德桌面、带MCP扩展的VS Code等）

安装

# 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

开发模式

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

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

可用工具

📖 第0层：只读工具

房间工具

  • list-joined-rooms -获取用户已加入的所有房间

    • 无需参数
    • 返回房间名称、ID和成员计数

  • get-room-info -获取详细的房间信息

    • roomId （string）：矩阵房间ID（例如。， !roomid:domain.com)
    • 返回名称、主题、设置、创建者和成员计数

  • get-room-members -列出房间中的所有成员

    • roomId （string）：矩阵室ID
    • 返回已加入成员的显示名称和用户ID

消息工具

  • get-room-messages -从房间检索最近的邮件

    • roomId （string）：矩阵室ID
    • limit （数字，默认值：20）：要检索的最大邮件数
    • 返回格式化的消息内容，包括文本和图像

  • get-messages-by-date -按日期范围筛选邮件

    • roomId （string）：矩阵室ID
    • startDate （字符串）：ISO 8601格式（例如。， 2024-01-01T00:00:00Z)
    • endDate （字符串）：ISO 8601格式
    • 在指定的时间范围内返回消息

  • identify-active-users -按邮件数查找最活跃用户

    • roomId （string）：矩阵室ID
    • limit （数字，默认值：10）：可返回的最大用户数
    • 返回按消息活动排序的用户

用户工具

  • get-user-profile -获取任何用户的个人资料信息

    • targetUserId （string）：目标用户的矩阵ID（例如。， @user:domain.com)
    • 返回显示名称、头像、状态和共享房间

  • get-my-profile -获取您自己的个人资料信息

    • 无需参数
    • 返回您的个人资料、设备信息和房间统计信息

  • get-all-users -列出客户已知的所有用户

    • 无需参数
    • 从客户端缓存返回显示名称和用户ID

搜索工具

  • search-public-rooms -探索公共房间加入
    • searchTerm （字符串，可选）：按名称或主题筛选
    • server （字符串，可选）：要搜索的特定服务器
    • limit （数字，默认值：20）：可返回的最大房间数
    • 返回房间详细信息、主题和成员计数

通知工具

  • get-notification-counts -检查未读消息和提及

    • roomFilter （字符串，可选）：要检查的特定房间ID
    • 返回未读计数、提及次数和最近的活动

  • get-direct-messages -列出所有DM对话

    • includeEmpty （boolean，默认值：false）：包括没有最近消息的DM
    • 返回DM合作伙伴、最新消息和未读状态

✏️ 第1层：行动工具

消息传递工具

  • send-message -向房间发送消息

    • roomId （string）：矩阵室ID
    • message （string）：消息内容
    • messageType （枚举：“text”|“html”|“emote”，默认值：“文本”）：消息格式
    • replyToEventId （字符串，可选）：要回复的事件ID
    • 支持纯文本、HTML格式和表情操作

  • send-direct-message -向用户发送私人消息

    • targetUserId （string）：目标用户的Matrix ID
    • message （string）：消息内容
    • 如果需要，自动创建DM室

房间管理工具

  • create-room -创建新的Matrix房间

    • roomName （string）：新房间的名称
    • isPrivate （布尔值，默认值：false）：房间隐私设置
    • topic （字符串，可选）：房间主题/描述
    • inviteUsers （数组，可选）：最初要邀请的用户ID
    • roomAlias （字符串，可选）：人类可读的房间别名
    • 创建具有适当安全设置的房间

  • join-room -按ID或别名加入房间

    • roomIdOrAlias （string）：要加入的房间ID或别名
    • 适用于邀请函和公共房间

  • leave-room -离开Matrix房间

    • roomId （string）：要离开的房间ID
    • reason （字符串，可选）：离职原因
    • 出于可选原因，干净地离开房间

  • invite-user -邀请用户进入房间

    • roomId （string）：邀请用户的房间
    • targetUserId （string）：要邀请的用户ID
    • 尊重房间权限和电源级别

房间管理工具

  • set-room-name -更新房间显示名称

    • roomId （string）：要修改的房间
    • roomName （string）：新房间名称
    • 需要适当的房间权限

  • set-room-topic -更新房间主题/描述

    • roomId （string）：要修改的房间
    • topic （string）：新房间主题
    • 需要适当的房间权限

身份验证和配置

身份验证模式

服务器支持两种身份验证模式：

OAuth模式(ENABLE_OAUTH=true)

  • 与您的身份提供者完全集成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"

客户端集成

克劳德代码

记住 MATRIX_ACCESS_TOKEN header是一个可选的header。如果令牌交换正常工作，则应将其删除。获得 MATRIX_MCP_TOKEN 来自MCP检查员。

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代码

记住 matrix_access_token header是一个可选的header。如果令牌交换正常工作，则应将其删除。

在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检验员测试

# 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支持：可配置的web客户端来源限制

建筑

服务器实现了三层架构：

  1. HTTP层 (http-server.ts)：与OAuth集成的Express服务器
  2. MCP层 (server.ts)：工具注册和请求路由
  3. 基质层 (tools/)：矩阵家庭服务器通信

每个工具都会创建临时Matrix客户端，这些客户端通过您配置的方法进行身份验证，执行请求的操作，并自动清理。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

相关 MCP