Unraid MCP 服务器

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

免责声明

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

• 这是一个非官方工具，与 Unraid, Inc. 没有任何关联或认可。

• 所有操作均限制为只读操作，以防止系统修改

• 始终妥善备份您的数据

• 在采取行动之前，请查看人工智能助手提供的所有信息和建议

• 开发人员不对使用该软件可能出现的任何问题负责

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

Related MCP server: Model Control Plane (MCP) Server

特征

• 系统信息：获取有关 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 文档