matrix-mcp-server

Matrix MCP 服务

一个全面的 Model Context Protocol (MCP) 服务，可安全访问 Matrix 主服务器功能。该服务使用 TypeScript 构建，使 MCP 客户端能够通过标准化接口与 Matrix 房间、消息、用户等进行交互。

功能

• 🔐 支持令牌交换的 OAuth 2.0 身份验证
• 📱 按功能层级组织的 15 个 Matrix 工具
• 🏠 支持通过可配置端点连接 多个主服务器
• 🔄 通过临时客户端管理实现 实时操作
• 🚀 可用于生产环境，提供全面的错误处理
• 📊 提供包含详细 Matrix 数据的 丰富响应

快速开始

前提条件

• Node.js 20+ 和 npm
• Matrix 主服务器访问权限（Synapse、Dendrite 等）
• MCP 客户端（Claude Desktop、带有 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（字符串）：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 格式（例如，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 - 列出所有私信对话

  • includeEmpty（布尔值，默认值：false）：是否包含近期没有消息的私信
  • 返回私信对象、最后一条消息和未读状态

✏️ 层级 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)：消息内容
  • 如有需要，会自动创建私信聊天室

聊天室管理工具

• 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)：新的聊天室主题
  • 需要相应的聊天室权限

身份验证与配置

身份验证模式

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

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"

客户端集成

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": "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 schema 全面验证参数
• 🌐 CORS 支持：可为 Web 客户端配置来源限制

架构

该服务采用三层架构：

1. HTTP 层（http-server.ts）：集成 OAuth 的 Express 服务
2. MCP 层（server.ts）：工具注册与请求路由
3. Matrix 层（tools/）：与 Matrix 主服务器通信

每个工具都会创建临时 Matrix 客户端，通过你配置的方式进行身份验证，执行所请求的操作，然后自动清理。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。