mcpField
U
Unraid RMCP

Unraid RMCP

本地服务
github.com云与基础设施1483 天前更新
代码仓库访问官网

关于 Unraid RMCP

Unraid RMCP 是一个用 Rust 编写的 MCP 服务与命令行工具，通过 GraphQL 管理 Unraid 系统的 NAS、Docker、虚拟机和存储。项目同时包含 Python 版服务与多个 Unraid OS 插件，面向 Unraid 用户与运维人员。

主要功能

  1. 01Rust 单一静态二进制的 MCP 服务与 CLI
  2. 02阵列状态与存储查询
  3. 03Docker 与虚拟机生命周期操作
  4. 04基于 unraid:read 与 unraid:admin 的权限范围
  5. 05支持 bearer 令牌与 OAuth 认证
  6. 06可选的工具投影模式配置

适用场景

  1. 01通过 AI 助手查询 Unraid 阵列与存储状态
  2. 02在命令行中检查 Unraid 设置并读取阵列信息
  3. 03借助 Agent 管理 Docker 容器与虚拟机的启停

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露基于 Unraid GraphQL API 的查询与变更工具。读取与变更操作分别需要 unraid:read 与 unraid:admin 权限范围。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "ai-dinglebear-unraid": {
      "command": "npx",
      "args": [
        "-y",
        "@dinglebear/unraid"
      ],
      "env": {
        "UNRAID_API_URL": "<UNRAID_API_URL>",
        "UNRAID_API_KEY": "<UNRAID_API_KEY>",
        "UNRAID_RMCP_VERSION": "<UNRAID_RMCP_VERSION>",
        "UNRAID_RMCP_REPO": "<UNRAID_RMCP_REPO>",
        "UNRAID_RMCP_RELEASE_BASE_URL": "<UNRAID_RMCP_RELEASE_BASE_URL>",
        "RUST_LOG": "<RUST_LOG>"
      }
    }
  }
}
启动命令npx -y @dinglebear/unraid
需要配置的环境变量
UNRAID_API_URLFull Unraid GraphQL endpoint URL.
UNRAID_API_KEY密钥Unraid API key.
UNRAID_RMCP_VERSIONOptional GitHub release tag override for the downloaded Unraid RMCP binary.
UNRAID_RMCP_REPOOptional GitHub owner/repo override for release asset downloads.
UNRAID_RMCP_RELEASE_BASE_URLOptional release download base URL override.
RUST_LOGTracing filter for Unraid RMCP logs.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@dinglebear/unraid0.6.3

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Unraid

PyPI ghcr.io

一个 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 / hatchlingcd unraid-py && uv run pytest && uv build --wheel
unraid-rs/runraid — Rust MCP 服务 + CLI（单个静态二进制文件）。Crate 在 crates.io 上的名称为 unraid-rmcp，另有兼容性 npm 启动器 @dinglebear/unraid。Rust / cargocd 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 + Vuebash plugins/mcp/scripts/build-txz.sh <ver> <runraid-binary>
plugins/incus/Unraid OS 插件，运行与局域网隔离的 Incus 系统容器（“开发容器”）。包含 NestJS/GraphQL unraid-api 后端。shell .plg + NestJS/Vuecd plugins/incus && ./scripts/verify-classic-package.sh && ./tests/classic-contract.sh
plugins/codex/Unraid OS 插件，内嵌 Codex chathead 应用服务器。shell .plg + Reactcd 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_URLUnraid GraphQL 端点（必填）
UNRAID_API_KEYUnraid API 的 x-api-key（必填）
UNRAID_API_SKIP_TLS_VERIFY接受自签名的 Unraid 证书（默认为 false）
UNRAID_RMCP_HOST / UNRAID_RMCP_PORTMCP 绑定地址（默认为 0.0.0.0:40010）
UNRAID_RMCP_TOKEN用于 /mcp 的静态 bearer token
UNRAID_RMCP_AUTH_MODEbearer（默认）或 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。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。