Unraid MCP 服务器

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

免责声明

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

• 这是一个非官方工具，与 Unraid, Inc. 没有任何关联或认可。
• 所有操作均限制为只读操作，以防止系统修改
• 始终妥善备份您的数据
• 在采取行动之前，请查看人工智能助手提供的所有信息和建议
• 开发人员不对使用该软件可能出现的任何问题负责

即使拥有只读权限，监控工具也有可能泄露敏感的系统信息。使用此软件即表示您确认并接受这些限制和风险。

特征

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

先决条件

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

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Unraid MCP 服务器：

手动安装

1. 克隆存储库：
   git clone https://github.com/jmagar/unraid-mcp.git cd unraid-mcp
2. 创建并激活虚拟环境：
   python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
3. 安装依赖项：
   pip install -r requirements.txt
4. 使用您的 Unraid API 凭据创建一个.env文件：
   cp .env.template .env # Edit .env with your actual API URL and key

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. 使用 GraphQL 沙盒（ http://your-unraid-server-ip/graphql测试 API

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

故障排除

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

用法

运行 MCP 服务器

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

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 功能
   • 处理请求验证和错误诊断

可用资源

可用工具

系统管理

阵列管理

Docker管理

虚拟机管理

通知管理

共享管理

磁盘管理

用户管理

API 密钥管理

与克劳德的整合

要将 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 请求。

执照

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

参考

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