Unraid MCP Server

基本能力

产品定位

Unraid MCP Server 是一个中间件，旨在通过 MCP 协议使 AI 助手能够安全地与 Unraid 服务器进行交互，提供丰富的系统监控和管理功能。

核心功能

• 系统信息：获取 CPU、内存、运行时间等详细信息
• 阵列管理：监控阵列状态
• Docker 管理：列出 Docker 容器和网络
• 虚拟机管理：列出虚拟机
• 磁盘信息：获取磁盘和未分配设备的详细信息
• 通知管理：查看和管理系统通知
• 共享管理：查看和管理网络共享
• 用户管理：列出用户
• API 密钥管理：列出 API 密钥
• 奇偶校验历史：查看奇偶校验检查历史
• 共享：浏览 Unraid 服务器上的用户共享
• 插件：查看已安装插件及其状态
• 错误处理：全面的错误处理和诊断信息
• 日志记录：详细的日志记录用于故障排除
• 模板资源：按名称访问特定容器和虚拟机

适用场景

• AI 助手与 Unraid 服务器的交互
• 远程监控 Unraid 服务器状态
• 系统管理员通过 AI 助手获取服务器信息
• 开发者集成 Unraid 管理功能到 AI 应用中

工具列表

系统管理

• get_system_info：获取详细的系统信息
• get_network_info：获取网络接口信息

阵列管理

• get_array_status：以人类可读的方式获取阵列状态
• get_parity_history：获取奇偶校验历史

Docker 管理

• get_docker_containers：获取 Docker 容器的信息
• get_docker_networks：获取 Docker 网络的信息
• list_containers：以人类可读的方式列出 Docker 容器

虚拟机管理

• get_vms：获取虚拟机的信息
• get_vm_details：获取特定虚拟机的详细信息
• list_vms：以人类可读的方式列出虚拟机

通知管理

• get_notifications：从 Unraid 服务器获取通知
• create_notification：创建新通知
• archive_notification：归档通知

共享管理

• get_shares：获取网络共享的信息
• get_share_details：获取特定共享的详细信息

磁盘管理

• get_disks：获取所有磁盘的信息
• get_disk_details：获取特定磁盘的信息
• get_unassigned_devices：获取未分配设备的信息

用户管理

• get_users：获取所有用户的信息

API 密钥管理

• get_api_keys：获取所有 API 密钥的信息

常见问题解答

• CORS 错误：确保客户端包含正确的 Origin 头，与服务器的 URL 匹配
• API 密钥权限不足：确保 API 密钥具有执行查询所需的角色和权限
• GraphQL 沙盒不可访问：检查 GraphQL 沙盒是否已启用并可访问
• 网络连接问题：检查与 Unraid 服务器的网络连接

使用教程

使用依赖

• Python 3.10 或更高版本
• 启用 API 的 Unraid 服务器
• 具有适当权限的 API 密钥

安装教程

通过 Smithery 安装

npx -y @smithery/cli install @jmagar/unraid-mcp --client claude

手动安装

1. 克隆仓库： bash git clone https://github.com/jmagar/unraid-mcp.git cd unraid-mcp

2. 创建并激活虚拟环境： bash python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate

3. 安装依赖： bash pip install -r requirements.txt

4. 创建 .env 文件并配置 Unraid API 凭据： bash cp .env.template .env # 编辑 .env 文件，填入实际的 API URL 和密钥

Unraid API 设置

1. 启用开发者模式和 GraphQL 沙盒： unraid-api developer 按照提示启用沙盒。

2. 创建具有必要权限的 API 密钥： unraid-api apikey --create 按照提示设置名称、描述、角色和权限。

3. 配置 .env 文件：

4. UNRAID_API_URL：GraphQL URL（例如 http://your-unraid-server-ip/graphql）

5. UNRAID_API_KEY：创建的 API 密钥

6. 在 http://your-unraid-server-ip/graphql 测试 API

调试方式

运行 MCP 服务器以与 AI 助手集成：

python run_server.py

检查日志文件 unraid_mcp.log 获取详细的错误信息。

许可证

该项目遵循 MIT 开源许可条款。