矩阵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
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": "@:",
"matrix_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客户端来源限制
建筑
服务器实现了三层架构：
- HTTP层 (
http-server.ts)：与OAuth集成的Express服务器 - MCP层 (
server.ts)：工具注册和请求路由 - 基质层 (
tools/)：矩阵家庭服务器通信
每个工具都会创建临时Matrix客户端，这些客户端通过您配置的方法进行身份验证，执行请求的操作，并自动清理。
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。