Unraid MCP Server：用 AI Agent 操控你的 NAS 服务器

痛点故事：半夜被服务器吵醒的管理员

凌晨两点，你的 Unraid NAS 发出风扇狂转的异常噪声。你从床上爬起来，打开手机远程桌面，连上 VPN，浏览器输入 Unraid WebUI 地址——结果页面卡住了。你不得不爬起来走到服务器前，接上显示器，一行行排查日志。这种场景，是每一个自托管服务器管理员都经历过的噩梦。

而今天，有了 unraid-mcp，你只需要对 AI 说一句话：「帮我查一下服务器为什么这么吵」，AI 就能通过 MCP 协议直接调用 Unraid 的 GraphQL API，查 CPU 温度、内存占用、磁盘健康状态，甚至直接帮你发一条通知。这不是科幻——这是 dinglebear-ai/unraid 已经实现的功能。

背景：MCP 协议与 Unraid 的相遇

Unraid 是全球最流行的家庭/工作室 NAS 操作系统之一，以其独特的「奇偶校验」存储方案和灵活的 Docker/VM 支持闻名。但 Unraid 原生 API 长期缺乏标准化接口，开发者往往需要写爬虫抓取 WebUI 的内部接口，维护成本极高。

Model Context Protocol（MCP）是 Anthropic 主导的 AI Agent 工具调用标准协议，旨在让 AI 模型能够以统一、安全的方式调用外部工具。unraid-mcp 正是将这两个生态连接起来的桥梁——它以 GraphQL 作为底层通信协议，将 Unraid 的所有管理功能封装成符合 MCP 标准的工具集，让 Claude、Codex、Gemini 等主流 AI Agent 都能直接操控 Unraid 服务器。

项目的作者是 jmagar，这个仓库在 2026-07-27 经历了重大架构重构：从原来的 unraid-mcp 单仓库演进为包含 Python MCP 服务器、Rust MCP 服务器、以及三个 Unraid OS 原生插件的完整 monorepo。

技术架构：双语言实现的精妙设计

项目采用 monorepo 结构，包含 6 个核心组件：

unraid-py（旗舰产品） 是 Python 实现的 MCP 服务器，通过 GraphQL 与 Unraid 通信。Python 版本发布到 PyPI（pip install unraid-mcp），安装方式极其简单：uvx unraid-mcp 即可启动。它提供了 19 个 action domain、共 179 个 subaction，几乎覆盖 Unraid 所有管理功能。

unraid-rs 是 Rust 实现的高性能版本，提供静态二进制（无需运行时依赖），通过 crates.io 分发（unraid-rmcp）。Rust 版本同时提供 MCP 服务和原生 CLI，适合对性能有极致要求的用户。

三个 Unraid OS 原生插件：

• plugins/mcp — 将 Python MCP 服务器直接安装到 Unraid 系统
• plugins/incus — 运行 Incus 系统容器（类"开发容器"），带 NestJS/GraphQL 后端
• plugins/codex — 内嵌 Codex AI 对话界面

Agent 插件：agents/unraid-py/ 和 agents/unraid-rs/ 分别针对 Claude Code 和 OpenAI Codex 提供了开箱即用的 MCP 插件配置，用户只需两行命令即可安装集成。

核心功能：从读查到写入的全套管理

MCP 工具以单一 unraid 工具对外暴露，通过 action/subaction 二级结构组织。19 个 action domain 包括：

此外，项目还支持 实时遥测订阅（Live Telemetry），通过 WebSocket 推送 CPU、内存、磁盘阵列状态、UPS 状态等实时数据。文档中明确标注了「破坏性操作」：array 阵列启停、VM 生命周期操作、Docker 容器启停等高危操作在 DESTRUCTIVE_ACTIONS.md 中有详细记录，且 MCP 服务器内置了确认机制防止误操作。

上手门槛：多层次安装，任选其一

项目提供了从「零配置」到「深度开发」的完整安装路径：

最简方式（Claude Code 用户）：只需两条命令 —— /plugin marketplace add dinglebear-ai/unraid 添加市场，然后 /plugin install unraid-mcp@unraid-mcp 安装插件。AI Agent 会引导你输入 Unraid API 地址和 Key，全程无需手动配置环境变量。

Docker 一键部署：在有 Docker 环境的机器上，docker compose up -d 即可启动 Python MCP 服务器。docker-compose 默认只在 127.0.0.1 暴露端口以确保安全，需要 API Key 认证才能访问。

pip/PyPI 方式：pip install unraid-mcp 后设置 UNRAID_API_URL 和 UNRAID_API_KEY 环境变量即可。

Rust 静态二进制：下载 crates.io 的 unraid-rmcp 二进制，运行 ./runraid setup plugin-hook 写入配置，再 ./runraid serve mcp 启动服务。

安全设计：API Key + OAuth + 破坏性操作确认

项目对安全性的重视体现在多个层面：

• 认证层：支持 API Key（x-api-key Header）和 OAuth 两种认证方式
• 读写分离：读取操作仅需 unraid:read scope，写入操作需要 unraid:admin scope
• 破坏性操作门控：VM/Docker/Array 的高危操作有明确文档记录，MCP 服务器内置确认提示
• 默认安全策略：docker-compose 默认只绑定 127.0.0.1，不对外暴露；若要公网暴露，必须开启 bearer token 认证
• TLS 跳过选项：对自签名证书的 Unraid 服务器提供了 UNRAID_API_SKIP_TLS_VERIFY 选项

代码质量：从 Linter 到 CI 的完整工程化

项目采用了极高的工程标准：

• Rust 端：cargo fmt、cargo clippy 强制代码风格和静态分析，-D warnings 将所有警告视为错误
• Python 端：使用 uv 替代 pip 作为包管理工具，pytest 单元测试
• CI/CD：release-please 管理 Python 和 Rust 版本的语义化版本发布
• Monorepo 管理：lefthook.yml 配置了 pre-commit hooks，mise.toml 统一工具链版本
• 安全扫描：.gitleaks.toml 防止敏感信息泄露，Dependabot 自动化依赖更新

局限与争议

必须依赖 Unraid 服务器：这是一个专门为 Unraid 设计的工具，对非 Unraid 用户完全没有价值。117 stars 的体量说明它是一个非常垂直的细分工具，而非通用解决方案。

API 版本锁定风险：Unraid 的 GraphQL API 并非完全稳定的公开接口，如果 Unraid 官方更改 API 结构，项目需要同步更新，存在一定维护依赖风险。

Python 版是主角：Rust 版虽然性能更优，但文档和社区关注度明显偏低，两者的功能同步状态需要持续关注。

行业意义：垂直场景 Agent 工具化的范式

unraid-mcp 代表了一种新兴的 AI 工具化路径：不为 AI 构建功能，而是让 AI 接入已有的专业工具。它不是要替代 Unraid WebUI，而是让 AI Agent 能够「理解」并「操控」Unraid。这种模式正在被复制到路由器、打印机、工业控制系统等专业领域——任何有 API 的系统，理论上都可以被 MCP 化。

项目从 2024 年的单仓库插件成长为一个包含多语言实现、多插件生态的完整工具链，Star 增长曲线稳定，是 homelab 和 self-hosted 社区中极具代表性的 AI 集成案例。