简介

一个基于Python的服务器，它使AI助手能够通过官方的Unraid GraphQL API与Unraid服务器进行交互，提供对系统信息、Docker容器、虚拟机、存储等的只读访问。

简介

一个基于Python的服务器，它使AI助手能够通过官方的Unraid GraphQL API与Unraid服务器进行交互，提供对系统信息、Docker容器、虚拟机、存储等的只读访问。

Unraid MCP 服务器

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

免责声明

自行承担风险使用：此软件提供通过 AI 助手访问您的 Unraid 服务器的功能。尽管此实现配置为只读以提高安全性，但在使用时仍应谨慎。

• 这是一个非官方工具，与 Unraid, Inc. 无关且未得到其认可。
• 所有操作仅限于只读动作，以防止系统修改。
• 始终保持数据的适当备份。
• 在采取行动之前，请审查 AI 助手提供的所有信息和建议。
• 开发者不对使用此软件可能引起的问题负责。

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

特性

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

前提条件

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

安装

通过 Smithery 安装

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

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 tokens。

故障排除

• 如果遇到 CORS 错误，请确保你的客户端包含了与服务器 URL 匹配的正确 Origin 头。
• 确保你的 API 密钥拥有执行查询所需的必要角色和权限。
• 检查 GraphQL 沙箱是否已启用并可访问。

使用

运行 MCP 服务器

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

# Run in stdio mode (for direct integration with AI assistants)
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 规范定义资源和工具
   • 将 Unraid 功能暴露给 AI 助手
   • 处理请求验证和错误诊断

可用资源

可用工具

系统管理

阵列管理

Docker 管理

虚拟机管理

通知管理

共享管理

磁盘管理

用户管理

API 密钥管理

与 Claude 集成

要使用 MCP 服务器与支持 stdio 模式的 Claude API 或其他 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_details 资源）
• "我安装了哪些插件？"

故障排除

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

常见问题：

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

贡献

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

许可证

本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。

参考资料

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

服务配置

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

来源

• 来源：github
• 链接：https://github.com/jmagar/unraid-mcp