Unraid MCP

Unraid

一个 Unraid 工具单体仓库：包含两个 MCP 服务（Python 和 Rust）、三个 Unraid OS 插件，以及用于展示这些工具的 Claude/Codex Agent 集成。

仓库名称。 本仓库于 2026-07-27 从 unraid-mcp 重命名为 unraid，并合并了原先独立的 runraid 和 incus-unraid 仓库。一些已部署插件的安装/更新 URL 仍依赖旧名称的重定向；迁移这些运行时 URL 需要专门发布一个版本。PyPI 包、容器镜像、Claude 插件和 Unraid .plg 仍均命名为 unraid-mcp——只有仓库名称变了。

组件

路径	说明	工具链	构建 / 测试
unraid-py/	unraid-mcp — Python MCP 服务（GraphQL），旗舰项目。以 unraid-mcp 名称发布到 PyPI。	Python / uv / hatchling	cd unraid-py && uv run pytest && uv build --wheel
unraid-rs/	runraid — Rust MCP 服务 + CLI（单个静态二进制文件）。Crate 在 crates.io 上的名称为 unraid-rmcp，另有兼容性 npm 启动器 @dinglebear/unraid。	Rust / cargo	cd unraid-rs && cargo fmt --check && cargo clippy --all-targets --features test-support -- -D warnings && cargo test
plugins/mcp/	Unraid OS 插件，将 Rust runraid MCP 服务安装到 Unraid 主机上。	shell .plg + Rust + Vue	bash plugins/mcp/scripts/build-txz.sh <ver> <runraid-binary>
plugins/incus/	Unraid OS 插件，运行与局域网隔离的 Incus 系统容器（“开发容器”）。包含 NestJS/GraphQL unraid-api 后端。	shell .plg + NestJS/Vue	cd plugins/incus && ./scripts/verify-classic-package.sh && ./tests/classic-contract.sh
plugins/codex/	Unraid OS 插件，内嵌 Codex chathead 应用服务器。	shell .plg + React	cd plugins/codex && ./tests/contract.sh
agents/unraid-py/	用于 Python 服务的 Claude Code / Codex 插件（name: unraid-mcp）。	—	—
agents/unraid-rs/	用于 Rust 服务的 Claude Code / Codex 插件（name: runraid）。	—	—

安装 Agent 插件（一个市场命令，两个清单）

/plugin marketplace add dinglebear-ai/unraid
/plugin install unraid-mcp@unraid-mcp   # Python server
/plugin install runraid@unraid-mcp      # Rust server

后缀 @unraid-mcp 是 .claude-plugin/marketplace.json 中声明的市场名称，不是仓库名称——尽管仓库现在是 dinglebear-ai/unraid，它仍保持为 unraid-mcp。

两个插件都从同一个仓库发布。Claude 读取 .claude-plugin/marketplace.json；Codex 读取 .agents/plugins/marketplace.json。meta-ci.yml 会确保两者列出的插件集合相同，因此不会出现不一致。

marketplace add 接受 owner/repo 简写（或完整 Git URL / 本地路径）。安装后，Claude Code 会提示设置连接参数（插件的 userConfig）。

插件凭据无需手动配置

这些 Agent 插件不包含 Claude Code 钩子，也不需要钩子：两个 .mcp.json 文件都会通过 ${user_config.*} 将插件设置直接映射到服务环境中。agents/unraid-rs 会配置端点、TLS、身份验证和工具选择器设置；agents/unraid-py 会配置 UNRAID_API_URL 和 UNRAID_API_KEY。在插件设置中填写后，服务会在下次启动时读取这些值。

可选：适用于希望将 ~/.unraid/.env 写入磁盘的非插件安装方式（systemd、Docker）：

runraid setup plugin-hook          # or: npx -y @dinglebear/unraid setup plugin-hook

unraid-py 快速入门（Python MCP 服务）

Python 服务是旗舰项目。完整文档涵盖安装、Claude Code / Codex / Gemini 配置、设置、身份验证、防护机制和工具功能，详见 unraid-py/README.md 和 unraid-py/docs/。它以 unraid-mcp 的名称发布到 PyPI（导入 包为 unraid_mcp），并通过 uvx unraid-mcp 启动。

unraid-rs 快速入门（Rust MCP 服务 + CLI）

cargo install --path unraid-rs --locked     # from the repository root
# Configure UNRAID_API_URL and UNRAID_API_KEY privately before querying.
runraid setup check                        # inspect setup without repairing files
runraid array                              # read array state
runraid serve mcp                          # MCP HTTP (default :40010; configure auth)

环境变量	用途
UNRAID_API_URL	Unraid GraphQL 端点（必填）
UNRAID_API_KEY	Unraid API 的 x-api-key（必填）
UNRAID_API_SKIP_TLS_VERIFY	接受自签名的 Unraid 证书（默认为 false）
UNRAID_RMCP_HOST / UNRAID_RMCP_PORT	MCP 绑定地址（默认为 0.0.0.0:40010）
UNRAID_RMCP_TOKEN	用于 /mcp 的静态 bearer token
UNRAID_RMCP_AUTH_MODE	bearer（默认）或 oauth

完整列表和 OAuth 变量详见：unraid-rs/AGENTS.md。

并非只读。 Rust 服务同时提供查询和变更操作。读取操作 需要 unraid:read 作用域；变更操作（VM 和 Docker 生命周期管理、阵列 启动/停止、通知写入）需要 unraid:admin。

开发和文档

请从 AGENTS.md 开始，该文件是规范的贡献指南。 CLAUDE.md 和 GEMINI.md 是指向它的符号链接，组件内也一样。 文档索引链接到 开发和验证、 架构和发布流程。

Rust MCP 支持 UNRAID_RMCP_PROJECTION=legacy（默认）、atomic 或 both。 所有投影共用已启用操作的策略、作用域和执行逻辑；atomic 模式并非第二个后端。有关选择器和迁移，请参阅 Rust README。

发布

发布分为两个通道。release-please 仅管理 unraid-py 和 unraid-rs——Python 服务沿用无前缀的 vX.Y.Z 标签（现有 用户群采用的方案），Rust 使用 unraid-rs-vX.Y.Z。Incus 和 Codex 插件 不使用 release-please：它们由 .github/scripts/plugin_calver.py 采用固定宽度的 YYYYMMDD.NNN 版本号和 incus-v* / codex-v* 标签进行版本管理（Unraid 将插件版本视为原始字符串进行比较，因此必须采用固定宽度）。

原生 MCP 插件由对应的 unraid-rs-vX.Y.Z 标签构建，Community Applications 从 unraid-plugin-latest 发布版本中读取滚动清单。插件 .txz 载荷作为 GitHub 发布资源提供，绝不纳入 git 跟踪。

许可证

MIT——详见 LICENSE。