内容
# 🚀 Unraid MCP 服务器
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
[](LICENSE)
**一个强大的 MCP（模型上下文协议）服务器，提供与 Unraid 服务器 GraphQL API 交互的全面工具。**
> [!NOTE]
> 该仓库是 [jmagar/unraid-mcp](https://github.com/jmagar/unraid-mcp) 的一个分支，但具有当前最新的 GraphQL 模式。
## ✨ 功能
- 🔧 **44 个工具**：通过 MCP 协议完成 Unraid 管理
- 🏗️ **模块化架构**：清洁、可维护和可扩展的代码库
- ⚡ **高性能**：具有优化超时的异步/并发操作
- 🔄 **实时数据**：用于实时日志流的 WebSocket 订阅
- 📊 **健康监测**：全面的系统诊断和状态
- 🐳 **Docker 就绪**：具有 Docker Compose 的完整容器化支持
- 🔒 **安全**：适当的 SSL/TLS 配置和 API 密钥管理
- 📝 **丰富日志记录**：具有轮换和多个级别的结构化日志记录
---
## 📋 目录
- [快速开始](#-快速开始)
- [安装](#-安装)
- [配置](#-配置)
- [可用工具和资源](#-可用工具和资源)
- [开发](#-开发)
- [架构](#-架构)
- [故障排除](#-故障排除)
---
## 🚀 快速开始
### 先决条件
- Docker 和 Docker Compose（推荐）
- 或 Python 3.10+，使用 [uv](https://github.com/astral-sh/uv) 进行开发
- 启用 GraphQL API 的 Unraid 服务器
### 1. 克隆仓库
```bash
git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp
```
### 2. 配置环境
```bash
cp .env.example .env
# 使用您的 Unraid API 详细信息编辑 .env
```
### 3. 使用 Docker 部署（推荐）
```bash
# 使用 Docker Compose 启动
docker compose up -d
# 查看日志
docker compose logs -f unraid-mcp
```
### 或 3. 运行开发环境
```bash
# 安装依赖项
uv sync
# 运行开发服务器
./dev.sh
```
---
## 📦 安装
### 🐳 Docker 部署（推荐）
运行 Unraid MCP 服务器的最简单方法是使用 Docker：
```bash
# 克隆仓库
git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp
# 设置所需的环境变量
export UNRAID_API_URL="http://your-unraid-server/graphql"
export UNRAID_API_KEY="your_api_key_here"
# 使用 Docker Compose 部署
docker compose up -d
# 查看日志
docker compose logs -f unraid-mcp
```
#### 手动 Docker 构建
```bash
# 手动构建和运行
docker build -t unraid-mcp-server .
docker run -d --name unraid-mcp \
--restart unless-stopped \
-p 6970:6970 \
-e UNRAID_API_URL="http://your-unraid-server/graphql" \
-e UNRAID_API_KEY="your_api_key_here" \
unraid-mcp-server
```
### 🔧 开发安装
用于开发和测试：
```bash
# 克隆仓库
git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp
# 使用 uv 安装依赖项
uv sync
# 安装开发依赖项
uv sync --group dev
# 配置环境
cp .env.example .env
# 使用您的设置编辑 .env
# 运行开发服务器
./dev.sh
```
---
## ⚙️ 配置
### 环境变量
在项目根目录中创建 `.env` 文件：
```bash
# 核心 API 配置（必需）
UNRAID_API_URL=https://your-unraid-server-url/graphql
UNRAID_API_KEY=your_unraid_api_key
# MCP 服务器设置
UNRAID_MCP_TRANSPORT=streamable-http # streamable-http（推荐），sse（已弃用），stdio
UNRAID_MCP_HOST=0.0.0.0
UNRAID_MCP_PORT=6970
# 日志记录配置
UNRAID_MCP_LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
UNRAID_MCP_LOG_FILE=unraid-mcp.log
# SSL/TLS 配置
UNRAID_VERIFY_SSL=true # true, false, 或 CA 捆绑路径
# 可选：日志流配置
# UNRAID_AUTOSTART_LOG_PATH=/var/log/syslog # 日志流资源的路径
```
### 传输选项
| 传输 | 描述 | 用例 |
|-----------|-------------|----------|
| `streamable-http` | 基于 HTTP（推荐） | 最兼容，性能最佳 |
| `sse` | 服务器发送事件（已弃用） | 仅限旧版支持 |
| `stdio` | 标准输入/输出 | 直接集成场景 |
---
## 🛠️ 可用工具和资源
### 系统信息和状态
- `get_system_info()` - 综合系统、操作系统、CPU、内存、硬件信息
- `get_array_status()` - 存储阵列状态、容量和磁盘详情
- `get_unraid_variables()` - 系统变量和设置
- `get_network_config()` - 网络配置和访问 URL
- `get_registration_info()` - Unraid 注册详情
### 存储管理
- `get_shares_info()` - 用户共享信息
- `list_physical_disks()` - 物理磁盘发现
- `get_disk_details(disk_id)` - SMART 数据和详细磁盘信息
- `list_available_log_files()` - 可用的系统日志
- `get_logs(path, tail_lines)` - 日志文件内容检索
- `get_share_details(name)` - 详细共享信息
- `get_pool_details(name)` - 详细池信息
- `get_cache_pool_details(name)` - 详细缓存池信息
- `get_filesystem_details(path)` - 文件系统使用和详情
### Docker 容器管理
- `list_docker_containers()` - 列出所有容器，带有缓存选项
- `manage_docker_container(id, action)` - 启动/停止容器（幂等）
- `get_docker_container_details(identifier)` - 详细容器信息
### 虚拟机管理
- `list_vms()` - 列出所有虚拟机及其状态
- `manage_vm(id, action)` - 虚拟机生命周期（启动/停止/暂停/恢复/重启）
- `get_vm_details(identifier)` - 详细虚拟机信息
### 云存储（RClone）
- `list_rclone_remotes()` - 列出配置的远程存储
- `get_rclone_config_form(provider)` - 配置模式
- `create_rclone_remote(name, type, config)` - 创建新的远程存储
- `delete_rclone_remote(name)` - 删除现有的远程存储
### 健康监测
- `health_check()` - 综合系统健康评估
### 连接管理
- `get_connect_settings()` - Unraid Connect 配置
- `get_connect_status()` - 连接状态
- `get_connect_vpn_config()` - VPN 配置详情
- `update_connect_settings(settings)` - 更新 Connect 设置
### 通知
- `get_notifications_overview()` - 按严重程度分类的通知数量
- `list_notifications(type, offset, limit)` - 过滤通知列表
- `dismiss_notification(id)` - .dismiss 通知
### 插件
- `list_plugins()` - 列出已安装的插件
- `get_plugin_details(name)` - 详细插件信息
- `manage_plugin(name, action)` - 安装/更新/删除插件
### 安全
- `get_security_settings()` - 安全配置
- `list_ssl_certificates()` - 列出 SSL 证书
- `get_certificate_details(id)` - 详细证书信息
- `update_security_settings(settings)` - 更新安全设置
### UPS 管理
- `get_ups_status()` - UPS 状态和指标
- `get_ups_settings()` - UPS 配置
- `update_ups_settings(settings)` - 更新 UPS 设置
### 实时订阅和资源
- `test_subscription_query(query)` - 测试 GraphQL 订阅
- `diagnose_subscriptions()` - 订阅系统诊断
### MCP 资源（实时数据）
- `unraid://logs/stream` - 使用 WebSocket 订阅从 `/var/log/syslog` 进行实时日志流传输
> **注意**：MCP 资源提供可以通过 MCP 客户端访问的实时数据流。日志流资源自动连接到您的 Unraid 系统日志并提供实时更新。
---
## 🔧 开发
### 项目结构
```
unraid-mcp/
├── unraid_mcp/ # 主包
│ ├── main.py # 入口点
│ ├── config/ # 配置管理
│ │ ├── settings.py # 环境和设置
│ │ └── logging.py # 日志记录设置
│ ├── core/ # 核心基础设施
│ │ ├── client.py # GraphQL 客户端
│ │ ├── exceptions.py # 自定义异常
│ │ └── types.py # 共享数据类型
│ ├── subscriptions/ # 实时订阅
│ │ ├── manager.py # WebSocket 管理
│ │ ├── resources.py # MCP 资源
│ │ └── diagnostics.py # 诊断工具
│ ├── tools/ # MCP 工具类别
│ │ ├── docker.py # 容器管理
│ │ ├── system.py # 系统信息
│ │ ├── storage.py # 存储和监控
│ │ ├── health.py # 健康检查
│ │ ├── virtualization.py # 虚拟机管理
│ │ ├── rclone.py # 云存储
│ │ ├── connect.py # 连接管理
│ │ ├── notifications.py # 通知管理
│ │ ├── plugins.py # 插件管理
│ │ ├── security.py # 安全管理
│ │ └── ups.py # UPS 管理
│ └── server.py # FastMCP 服务器设置
├── logs/ # 日志文件（自动创建）
├── dev.sh # 开发脚本
└── docker-compose.yml # Docker Compose 部署
```
### 代码质量命令
```bash
# 格式化代码
uv run black unraid_mcp/
# 检查代码
uv run ruff check unraid_mcp/
# 类型检查
uv run mypy unraid_mcp/
# 运行测试
uv run pytest
```
### 开发工作流程
```bash
# 启动开发服务器（安全地终止现有进程）
./dev.sh
# 仅停止服务器
./dev.sh --kill
```
---
## 🏗️ 架构
### 核心原则
- **模块化设计**：在专注的模块中分离关注点
- **异步优先**：所有操作都是非阻塞和并发安全的
- **错误恢复能力**：具有渐进式降级的全面错误处理
- **配置驱动**：基于环境的配置，带有验证
- **可观察性**：结构化日志记录和健康监测
### 关键组件
| 组件 | 目的 |
|-----------|---------|
| **FastMCP 服务器** | MCP 协议实现和工具注册 |
| **GraphQL 客户端** | 具有超时管理的异步 HTTP 客户端 |
| **订阅管理器** | 实时数据的 WebSocket 连接 |
| **工具模块** | 领域特定的业务逻辑（Docker、虚拟机等） |
| **配置系统** | 环境加载和验证 |
| **日志记录框架** | 具有文件轮换的结构化日志记录 |
---
## 🐛 故障排除
### 常见问题
**🔥 端口已被占用**
```bash
./dev.sh # 自动终止现有进程
```
**🔧 连接被拒绝**
```bash
# 检查 Unraid API 配置
curl -k "${UNRAID_API_URL}" -H "X-API-Key: ${UNRAID_API_KEY}"
```
**📝 导入错误**
```bash
# 重新安装依赖项
uv sync --reinstall
```
**🔍 调试模式**
```bash
# 启用调试日志记录
export UNRAID_MCP_LOG_LEVEL=DEBUG
uv run unraid-mcp-server
```
### 健康检查
```bash
# 通过 MCP 客户端使用内置的健康检查工具
# 或在以下位置检查日志：logs/unraid-mcp.log
```
---
## 📄 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
---
## 🤝 贡献
1. 分叉仓库
2. 创建一个功能分支：`git checkout -b feature/amazing-feature`
3. 运行测试：`uv run pytest`
4. 提交更改：`git commit -m 'Add amazing feature'`
5. 推送到分支：`git push origin feature/amazing-feature`
6. 打开拉取请求
---
## 📞 支持
- 📚 文档：查看内联代码文档
- 🐛 问题：[GitHub 问题](https://github.com/jmagar/unraid-mcp/issues)
- 💬 讨论：使用 GitHub 讨论提问
---
*为 Unraid 社区构建 ❤️*
