Unraid MCP 服务器

一个基于 Python 的 MCP (模型上下文协议) 服务器，使 AI 助手能够通过官方 Unraid GraphQL API 与 Unraid 服务器交互。

免责声明

使用风险自负: 此软件允许 AI 助手访问您的 Unraid 服务器。虽然此实现配置为只读以提高安全性，但在使用时仍应谨慎。

• 这是一个非官方工具，不隶属于 Unraid, Inc.，也不受其认可。
• 所有操作都仅限于只读操作，以防止系统修改
• 始终维护数据的适当备份
• 在采取行动之前，请审查 AI 助手提供的所有信息和建议
• 开发人员不对因使用此软件而可能出现的任何问题负责

即使是只读访问，监控工具也可能暴露敏感的系统信息。通过使用此软件，您承认并接受这些限制和风险。

功能

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

前提条件

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

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Unraid MCP Server：

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

手动安装

1. 克隆存储库：

   git clone https://github.com/jmagar/unraid-mcp.git
   cd unraid-mcp
   

2. 创建并激活虚拟环境：

   python3 -m venv venv
   source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 使用您的 Unraid API 凭据创建一个 .env 文件：

   cp .env.template .env
   # 使用您的实际 API URL 和密钥编辑 .env
   

Unraid API 设置

要使用此 MCP 服务器，您需要在 Unraid 服务器上设置 Unraid API：

1. 使用 CLI 启用开发者模式和 GraphQL 沙箱：

   unraid-api developer
   

   按照提示启用沙箱。

2. 创建具有必要权限的 API 密钥：

   unraid-api apikey --create
   

   按照提示设置名称、描述、角色和权限。

3. 使用以下内容配置您的 .env 文件：

   • UNRAID_API_URL: GraphQL URL (例如，http://your-unraid-server-ip/graphql)
   • UNRAID_API_KEY: 您创建的 API 密钥

4. 使用 http://your-unraid-server-ip/graphql 上的 GraphQL 沙箱测试 API

注意: Unraid API 使用 x-api-key 标头进行身份验证，而不是 Bearer 令牌。

故障排除

• 如果您收到 CORS 错误，请确保您的客户端包含与服务器 URL 匹配的正确 Origin 标头。
• 确保您的 API 密钥具有您尝试执行的查询所需的角色和权限。
• 检查 GraphQL 沙箱是否已启用且可访问。

用法

运行 MCP 服务器

在 stdio 模式下运行服务器，以便与 AI 助手集成：

# 在 stdio 模式下运行（用于与 AI 助手直接集成）
python run_server.py

stdio 模式适用于：

• 与支持 MCP 协议的 AI 助手直接集成
• 使用 Anthropic Python SDK 进行测试
• 与 Cursor 中的 Claude 集成

在 stdio 模式下运行时，服务器从标准输入读取并写入标准输出，遵循 MCP 协议格式。这允许与 AI 助手直接通信，而无需 HTTP 传输。

服务器架构

该服务器使用 FastMCP 框架构建，包括：

1. Unraid API 客户端 (unraid_client.py):

   • 处理与 Unraid 服务器的 GraphQL 通信
   • 管理身份验证和错误处理
   • 提供一致的错误报告

2. MCP 服务器 (server.py):

   • 根据 MCP 规范定义资源和工具
   • 向 AI 助手公开 Unraid 功能
   • 处理请求验证和错误诊断

可用资源

资源 URI	描述
unraid://system/info	系统信息 (CPU, 内存, 运行时间)
unraid://system/plugins	已安装的插件
unraid://docker/containers	所有 Docker 容器的列表
unraid://docker/{container_name}	特定容器的详细信息
unraid://array/status	当前阵列状态
unraid://vms/list	所有虚拟机的列表
unraid://vms/{vm_name}	特定 VM 的详细信息
unraid://storage/shares	用户共享信息

可用工具

系统管理

工具名称	描述
get_system_info	获取详细的系统信息
get_network_info	获取网络接口信息

阵列管理

工具名称	描述
get_array_status	以人类可读的方式获取阵列状态
get_parity_history	获取奇偶校验检查历史

Docker 管理

工具名称	描述
get_docker_containers	获取有关 Docker 容器的信息
get_docker_networks	获取有关 Docker 网络的信息
list_containers	以人类可读的方式列出 Docker 容器

VM 管理

工具名称	描述
get_vms	获取有关虚拟机的信息
get_vm_details	获取有关特定 VM 的详细信息
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 密钥的信息

与 Claude 集成

要将 MCP 服务器与 Claude API 或其他支持 stdio 模式的 AI 助手一起使用：

1. 创建一个配置文件 (例如，unraid_mcp_config.json):

   {
     "mcpServers": {
       "unraid": {
         "command": "/path/to/python",
         "args": ["/path/to/unraid-mcp/run_server.py"],
         "env": {
           "UNRAID_API_URL": "http://your-unraid-server:port/graphql",
           "UNRAID_API_KEY": "your-api-key",
           "LOG_LEVEL": "INFO",
           "CLAUDE_MCP_SERVER": "true"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

注意: 对于 Windows 用户，请确保在路径中使用双反斜杠 (例如，C:\\Users\\username\\unraid-mcp\\run_server.py)

示例查询

• "我的 Unraid 服务器上当前的 CPU 使用率是多少？"
• "列出我的所有 Docker 容器"
• "告诉我关于我的 Plex 容器的信息" (使用 container_details 资源)
• "启动 Plex 容器"
• "我的阵列状态如何？"
• "我的 Unraid 服务器上有多少可用空间？"
• "向我显示有关我的 Windows VM 的详细信息" (使用 vm_details 资源)
• "我安装了哪些插件？"

故障排除

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

常见问题：

• .env 文件中的 API URL 或密钥不正确
• 与 Unraid 服务器的网络连接问题
• API 密钥的权限不足
• 未在 Unraid 服务器上启用开发者模式
• API 密钥没有必要的角色

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

参考

• 模型上下文协议
• MCP Python SDK
• Unraid API 文档