星战科技xingzhan.cloud
返回市场
矩阵-MCP服务器

矩阵-MCP服务器

作者：mjknowles27 星标更新：2025-08-20
安装使用来源：spider==github.com

项目介绍

Matrix MCP 服务器

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

特性

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

快速开始

先决条件

  • Node.js 20+ 和 npm
  • Matrix家服务器 访问权限（如Synapse、Dendrite等）
  • MCP客户端（如Claude桌面版、VS Code带MCP扩展等）

安装

# 克隆仓库
git clone <repository-url>
cd matrix-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 配置环境
cp .env.example .env
# 编辑.env文件以设置您的配置

# 启动服务器
npm start

开发模式

# 启动热重载（OAuth禁用以便于测试）
npm run dev

# 或启用OAuth启动
ENABLE_OAUTH=true npm run dev

可用工具

📖 第0层：只读工具

房间工具

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

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

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

    • roomId (字符串)：Matrix房间ID（例如，!roomid:domain.com）
    • 返回名称、主题、设置、创建者和成员数量

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

    • roomId (字符串)：Matrix房间ID
    • 返回已加入成员的显示名称和用户ID

消息工具

  • get-room-messages - 从房间中检索最近的消息

    • roomId (字符串)：Matrix房间ID
    • limit (数字，默认值：20)：要检索的最大消息数
    • 返回格式化后的消息内容，包括文本和图片

  • get-messages-by-date - 按日期范围过滤消息

    • roomId (字符串)：Matrix房间ID
    • startDate (字符串)：ISO 8601格式（例如，2_2024-01-01T00:00:00Z）
    • endDate (字符串)：ISO 8601格式
    • 返回指定时间段内的消息

  • identify-active-users - 根据消息数量找到最活跃的用户

    • roomId (字符串)：Matrix房间ID
    • limit (数字，默认值：10)：返回的最大用户数
    • 返回按消息活动排序的用户

用户工具

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

    • targetUserId (字符串)：目标用户的Matrix 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 (布尔，默认值：false)：是否包含没有最近消息的DM
    • 返回DM伙伴、最后消息和未读状态

✏️ 第1层：操作工具

消息工具

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

    • roomId (字符串)：Matrix房间ID
    • message (字符串)：消息内容
    • messageType (枚举："text" | "html" | "emote"，默认值："text")：消息格式
    • replyToEventId (字符串，可选)：回复事件ID
    • 支持纯文本、HTML格式和表情动作

  • send-direct-message - 向用户发送私信

    • targetUserId (字符串)：目标用户的Matrix ID
    • message (字符串)：消息内容
    • 如需自动创建DM房间

房间管理工具

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

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

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

    • roomIdOrAlias (字符串)：要加入的房间ID或别名
    • 支持邀请和公共房间

  • leave-room - 离开Matrix房间

    • roomId (字符串)：要离开的房间ID
    • reason (字符串，可选)：离开的原因
    • 清洁地退出房间，并可选地给出原因

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

    • roomId (字符串)：要邀请用户的房间
    • targetUserId (字符串)：要邀请的用户ID
    • 尊重房间权限和权力等级

房间管理工具

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

    • roomId (字符串)：要修改的房间
    • roomName (字符串)：新的房间名称
    • 需要适当的房间权限

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

    • roomId (字符串)：要修改的房间
    • topic (字符串)：新的房间主题
    • 需要适当的房间权限

身份验证与配置

身份验证模式

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

OAuth模式 (ENABLE_OAUTH=true)

  • 完整的OAuth 2.0集成与您的身份提供商
  • 支持令牌交换以用于Matrix家服务器的身份验证
  • 通过适当的令牌管理实现安全的多用户访问
  • 推荐用于生产部署

开发模式 (ENABLE_OAUTH=false)

  • 直接访问，无需OAuth身份验证
  • 需要在头部提供Matrix访问令牌
  • 适用于测试和开发的简化设置
  • 不推荐用于生产

环境变量

创建一个.env文件并填写您的配置：

# 核心配置
PORT=3000
ENABLE_OAUTH=true                    # 启用OAuth身份验证
ENABLE_TOKEN_EXCHANGE=true           # 交换OAuth令牌以获取Matrix令牌
CORS_ALLOWED_ORIGINS=""              # 允许的来源（逗号分隔，空表示允许所有）

# HTTPS配置（可选）
ENABLE_HTTPS=false
SSL_KEY_PATH="/path/to/private.key"
SSL_CERT_PATH="/path/to/certificate.crt"

# 身份提供商（OAuth模式）
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配置
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头部是一个可选头部。如果您有令牌交换工作，请删除它。从MCP Inspector获取MATRIX_MCP_TOKEN。

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": "您的OAuth访问令牌"
    }
  ]
}

使用MCP Inspector进行测试

# 启动服务器
npm run dev

# 在另一个终端运行检查器
npx @modelcontextprotocol/inspector

连接到http://localhost:3000/mcp进行身份验证并测试所有可用工具。

开发

可用脚本

npm run build      # 将TypeScript编译到dist/
npm run dev        # 带热重载的开发服务器
npm run start      # 生产服务器
npm run lint       # 运行ESLint
npm run test       # 运行测试

项目结构

src/
├── http-server.ts           # 主HTTP服务器入口点
├── server.ts               # MCP服务器配置
├── tools/                  # 工具实现
│   ├── tier0/             # 只读工具
│   │   ├── rooms.ts       # 房间信息工具
│   │   ├── messages.ts    # 消息检索工具
│   │   ├── users.ts       # 用户个人资料工具
│   │   ├── search.ts      # 房间搜索工具
│   │   └── notifications.ts # 通知工具
│   └── tier1/             # 操作工具
│       ├── messaging.ts   # 消息发送工具
│       ├── room-management.ts # 房间生命周期工具
│       └── room-admin.ts  # 房间管理工具
├── matrix/                # Matrix客户端管理
├── utils/                 # 辅助工具
└── types/                 # TypeScript类型定义

安全考虑

  • 🔐 令牌管理：所有Matrix客户端都是临时的，在操作后会被清理
  • 🛡️ OAuth集成：通过OAuth代理防止直接暴露Matrix令牌
  • 🔍 权限检查：尊重Matrix房间的权力等级和权限
  • 🚫 输入验证：使用Zod模式进行全面的参数验证
  • 🌐 CORS支持：为Web客户端配置源限制

架构

服务器实现了三层架构：

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

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

许可证

本项目采用MIT许可证 - 查看LICENSE文件了解详情。