Unraid MCP

一个本地 Model Context Protocol 服务器，让 AI 客户端能够通过 Unraid 官方的 GraphQL API 检查和管理 Unraid 服务器。

AI 辅助开发声明： 本项目的设计、研究、实现、文档编写和测试均得到了 AI 编码代理的大量协助。它不是 Unraid 官方项目。在授予其对 Unraid 服务器的访问权限之前，请自行审查源代码、权限和安全设置，尤其是在启用变更工具之前。

该 MCP 默认只读。变更工具在通过环境变量显式启用之前完全不会注册，而永久性/高风险操作还有第二道门槛。

环境要求

• Node.js 22 或更高版本

• pnpm 11

• Unraid 7.2 或更高版本，其中 API 已内置在操作系统中

• 一个 Unraid API 密钥

Unraid 7.0-7.1 可以通过 Unraid Connect 插件暴露 API v4，但 Unraid 官方文档将该组合标记为有限支持。本项目中的 GraphQL 文档针对 API v4.35.1，随 Unraid 7.3.2 一起提供。较旧的 API 版本可能会拒绝较新的查询，例如指标、日志或 UPS 字段。

Related MCP server: GraphQL MCP Toolkit

Unraid 设置

1. 在 Unraid WebGUI 中打开 设置 > 管理访问 > API 密钥。

2. 为此 MCP 创建一个密钥。

3. 从 VIEWER 角色开始，以获得只读访问权限。

4. 将生成的密钥存储在 UNRAID_API_KEY 中；切勿将其放入源代码管理或命令行参数中。

等效的 Unraid 终端命令是：

unraid-api apikey --create --name "Unraid MCP read only" --roles VIEWER --json

对于变更访问，优先使用细粒度权限而非 ADMIN。只选择你计划启用的工具所使用的资源，例如 ARRAY、DOCKER、VMS 和 NOTIFICATIONS，并搭配 READ_ANY、UPDATE_ANY，仅在需要时使用 DELETE_ANY。

此 MCP 不需要 GraphQL Sandbox。在开发环境之外请保持其禁用状态，因为启用它也会启用模式自省（schema introspection）。

安装

pnpm install --frozen-lockfile
pnpm build

依赖项使用精确版本锁定，安装时冻结 lockfile。pnpm 还会拒绝发布时间不足七天的版本（包括缺少发布时间的包），验证包/存储完整性，阻止未声明的生命周期脚本，并拒绝包信任降级。undici-types@6.21.0 的特定版本信任例外是固定的 @types/node 所要求的；年龄、完整性和 lockfile 检查仍然适用于它。要在审查依赖并等待隔离期结束后有意更新依赖，请使用精确版本并显式允许 lockfile 变更：

pnpm update --exact --no-frozen-lockfile package-name@x.y.z
pnpm verify
pnpm audit

在接受更新之前，请审查 package.json 和 pnpm-lock.yaml。不要在不保留这些控制措施的情况下添加自动化依赖更新任务。

在启动 MCP 的环境中设置配置：

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"
node /absolute/path/to/unraid-mcp/dist/index.js

UNRAID_URL 可以是 WebGUI 的源（origin），此时会自动添加 /graphql，也可以是精确的 GraphQL 端点。请直接配置最终的 HTTPS URL；重定向会被拒绝，这样 API 密钥就不会被转发到其他源。

容器镜像

带版本号的发布镜像已发布到 Docker Hub，支持 linux/amd64 和 linux/arm64。部署时应固定版本或镜像摘要，而不是依赖可变的 latest 标签：

docker pull lemanjo/unraid-mcp:0.1.1

最终镜像使用摘要固定的 Distroless Node.js 运行时。它没有 shell、包管理器、npm 或其他构建工具，并以数字非 root 用户身份运行。容器构建会使用 Trivy 进行扫描，当存在可修复的严重或高危漏洞时，会在登录注册表之前失败。

在你的 Unraid 服务器或其他 Docker 主机上构建生产镜像：

docker build --tag unraid-mcp:0.1.1 .

本地 stdio 容器

默认传输方式是 stdio。--env NAME 从启动环境转发值，而不会将机密信息放入镜像或命令行参数中：

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

以相同方式转发任何可选配置，例如 --env UNRAID_ALLOW_MUTATIONS。对于自定义 CA 文件，请以只读方式挂载并配置其容器路径：

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  --env UNRAID_CA_CERT_PATH=/certs/unraid-ca.pem \
  --volume /host/path/unraid-ca.pem:/certs/unraid-ca.pem:ro \
  unraid-mcp:0.1.1

在 stdio 模式下，镜像不会监听端口。AI 主机使用 docker run --rm -i 启动它并管理其生命周期。

常驻远程 HTTP 容器

当容器与 AI 客户端运行在不同的机器上时，请使用带认证的 Streamable HTTP。在受信任的机器上生成持久化的 MCP 令牌：

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-unraid-api-key"
export MCP_ALLOWED_HOSTS="mcp-server.example,192.168.1.20"

启动远程容器：

docker network create unraid-mcp-backend

docker run -d \
  --name unraid-mcp \
  --restart unless-stopped \
  --network unraid-mcp-backend \
  --env MCP_TRANSPORT=http \
  --env MCP_HOST=0.0.0.0 \
  --env MCP_PORT=3000 \
  --env MCP_ALLOWED_HOSTS \
  --env MCP_AUTH_TOKEN \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

当绑定 IPv4 或 IPv6 通配符地址时，MCP_ALLOWED_HOSTS 是必需的。列出客户端或反向代理将放入 HTTP Host 头中的每个主机名或 IP 地址。条目不包含端口，IPv6 条目使用方括号。健康检查始终包含 localhost 值。

如果省略 MCP_AUTH_TOKEN，服务器会生成一个加密随机的 256 位令牌，并在启动时打印一次：

docker logs unraid-mcp

查找 Generated MCP auth token:。任何能读取该日志的人都可以访问 MCP，而且当该变量未设置时，每次进程重启后都会生成新令牌。对于稳定的生产部署，请显式设置 MCP_AUTH_TOKEN。MCP 令牌与 UNRAID_API_KEY 是分开的；远程 AI 客户端只需要 MCP 令牌。

HTTP 监听器有意使用纯 HTTP。示例没有发布其端口；请将 Caddy、Nginx 或 Traefik 容器加入 unraid-mcp-backend 网络，并代理到 http://unraid-mcp:3000。对于主机安装的代理，Docker 28 或更高版本可以发布 127.0.0.1:3000:3000；较旧的 Docker 版本（包括某些 Unraid 版本）可能会将 localhost 发布的端口暴露到同一二层网络，因此请改用私有网络或显式防火墙规则。不要将端口 3000 直接暴露到互联网。容器健康检查调用 GET /health；MCP 流量使用 /mcp。

内置的认证限流识别直接 TCP 对端。在反向代理后面，还需要在代理上配置认证速率限制，因为所有被代理的客户端可能共享同一个对端地址。不要转发不受信任的 Host 值；要么保留外部主机名并将其包含在 MCP_ALLOWED_HOSTS 中，要么将其重写为固定的白名单主机名。

本地 Docker 客户端配置

通过 Docker 守护进程启动镜像的 OpenCode 配置如下：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}"
      }
    }
  }
}

AI 主机使用的 Docker 守护进程必须能够访问该镜像。更改配置后请重启 OpenCode。

配置

请使用 UNRAID_CA_CERT 或 UNRAID_CA_CERT_PATH 之一，不要同时使用。优先信任 Unraid 的证书或本地 CA。UNRAID_TLS_SKIP_VERIFY=true 是明确的最后手段，会打印警告；它不会全局改变其他 Node.js 连接的 TLS 行为。

对于隔离的遗留网络支持纯 HTTP，但会打印警告，因为 API 密钥和所有服务器数据都会以未加密方式传输。

AI 客户端设置

OpenCode

在启动 OpenCode 之前导出环境变量，然后将此本地 MCP 添加到 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": ["node", "/absolute/path/to/unraid-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}",
        "UNRAID_CA_CERT_PATH": "{env:UNRAID_CA_CERT_PATH}",
        "UNRAID_ALLOW_MUTATIONS": "{env:UNRAID_ALLOW_MUTATIONS}",
        "UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS": "{env:UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS}"
      }
    }
  }
}

删除未设置的可选环境条目。更改配置后请重启 OpenCode。

要连接到常驻 HTTP 容器，请在 OpenCode 机器上导出其 MCP 令牌并配置远程服务器：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "remote",
      "url": "https://mcp-server.example/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MCP_AUTH_TOKEN}"
      }
    }
  }
}

使用 HTTPS 反向代理 URL，而不是 Unraid GraphQL URL。OpenCode 将 MCP_AUTH_TOKEN 发送给 MCP；只有 MCP 容器将 UNRAID_API_KEY 发送给 Unraid。

Claude Code

在启动 Claude Code 之前导出 UNRAID_URL 和 UNRAID_API_KEY。对于项目范围，请在你使用 Claude Code 的项目中创建 .mcp.json：

{
  "mcpServers": {
    "unraid": {
      "command": "node",
      "args": ["/absolute/path/to/unraid-mcp/dist/index.js"],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Claude Code 会从其环境中展开 ${VAR} 引用。因此配置可以共享而无需存储 API 密钥。仅在设置了可选变量时才将其添加到 env 中，例如 "UNRAID_ALLOW_MUTATIONS": "${UNRAID_ALLOW_MUTATIONS}"。

要改为启动容器镜像，请使用：

{
  "mcpServers": {
    "unraid": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

运行 claude mcp list 验证服务器，然后在 Claude Code 中使用 /mcp 检查其状态和工具。Claude Code 在使用项目范围的 .mcp.json 服务器之前会请求批准。如果你更倾向于在 ~/.claude.json 中进行私有的跨项目配置，请在 Claude Code 的 MCP 命令中使用 --scope user。

对于常驻 HTTP 容器，请改用此 .mcp.json 条目：

{
  "mcpServers": {
    "unraid": {
      "type": "http",
      "url": "https://mcp-server.example/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

在启动 Claude Code 之前导出 MCP_AUTH_TOKEN。${MCP_AUTH_TOKEN} 引用会被展开，而不会将其值存储在项目配置中。

Codex CLI 和 IDE

Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用共享 MCP 配置。导出所需变量，然后将此条目添加到 ~/.codex/config.toml，或添加到受信任项目中的 .codex/config.toml：

[mcp_servers.unraid]
command = "node"
args = ["/absolute/path/to/unraid-mcp/dist/index.js"]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

env_vars 从 Codex 的环境转发值，而不会将其写入 config.toml。将任何已启用的可选设置添加到该列表中，例如 UNRAID_CA_CERT_PATH 或 UNRAID_ALLOW_MUTATIONS。

要改为启动容器镜像，请使用：

[mcp_servers.unraid]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "--env",
  "UNRAID_URL",
  "--env",
  "UNRAID_API_KEY",
  "unraid-mcp:0.1.1",
]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

writes 审批模式会针对未被标记为只读的工具提示审批。运行 codex mcp list 验证服务器，并在 Codex TUI 中使用 /mcp 检查已连接的工具。编辑共享配置后，重启 IDE 扩展或 ChatGPT 桌面应用。

对于常驻 HTTP 容器，请改用以下条目：

[mcp_servers.unraid]
url = "https://mcp-server.example/mcp"
bearer_token_env_var = "MCP_AUTH_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Codex 从其本地环境读取 Bearer 令牌，并且不会将该值存储在 config.toml 中。

Claude Desktop 和其他 stdio 主机

配置主机以启动：

node /absolute/path/to/unraid-mcp/dist/index.js

让主机进程从操作系统、服务管理器或其密钥管理器继承所需的环境变量。不要将 API 密钥放在 args 数组中。如果主机支持按服务器设置环境值但不支持密钥引用，请注意这些值存储在该主机的配置文件中。

MCP Inspector

导出变量后，即可交互式地检查和调用工具：

pnpm dlx @modelcontextprotocol/inspector node dist/index.js

Inspector 有意不作为项目依赖项；请调用你的环境所批准的版本。

工具

以下只读工具始终注册：

UNRAID_ALLOW_MUTATIONS=true 添加：

UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS=true 额外添加：

它还允许 unraid_control_parity_check 以 correct=true 启动。

MCP 注解只是给客户端的提示，而非访问控制。环境门控和 Unraid API 密钥自身的权限才是实际的控制手段。

API 限制

当前官方 schema 并未提供所有 WebGUI 操作。特别是：

• 共享为只读；不支持创建/编辑共享。

• Docker 容器可以控制、更新和移除，但不能创建或编辑。

• VM 可以控制，但不能创建、编辑、克隆、快照或删除。

• 主机关机/重启的变更操作未发布。

• 完整的 SMART 报告和 SMART 自检控制未发布。

• Docker restart 在 API v4.35.1 之后才添加，本兼容性目标有意不使用它。

• 奇偶校验变更的响应类型被 Unraid 标记为开发中。

有关官方来源引用和兼容性详细信息，请参阅 docs/api-capabilities.md。

开发

pnpm typecheck
pnpm test
pnpm build
# Or run all three:
pnpm verify

测试使用本地模拟 HTTP 服务器，以及内存型和 Streamable HTTP 类型的 MCP 客户端。它们不需要 Docker 或正在运行的 Unraid 服务器。

容器发布

GitHub Actions 针对拉取请求和对 main 的更改构建容器并进行漏洞扫描，无需使用注册表凭据。仅当发布带有语义化版本号的 GitHub Release（例如 v0.1.1）时才会发布。发布工作流在访问受保护的 dockerhub 环境的 DOCKERHUB_TOKEN 之前会扫描构建的镜像，然后发布版本、提交以及（对于稳定版本）latest 标签，并附带 SBOM 和来源证明。

安全说明

• Stdio 仍然是默认设置，不会打开监听的网络端口。

• HTTP 模式需要 Bearer 身份验证。缺失的令牌使用 256 位加密随机性生成，并有意写入启动日志。

• 生成的令牌是操作密钥：请限制日志访问，并为稳定部署配置 MCP_AUTH_TOKEN。

• HTTP 模式会验证 Host 和 Origin 头，对失败的身份验证进行速率限制，限制请求体大小，并默认绑定到回环地址。

• 内置 HTTP 监听器不提供 TLS。请使用 HTTPS 反向代理，不要将其直接暴露到互联网。

• 它从不将应用程序日志写入 stdout，stdout 保留用于 MCP JSON-RPC。

• 它不接受来自模型的任意 GraphQL 文档。

• 它不跟随重定向，并限制响应大小、日志行数和请求持续时间。

• 客户端取消会中止本地 HTTP 请求；已被 Unraid 接受的变更无法回滚。

• 如果 GraphQL 错误包含所配置的 API 密钥，则会将其移除。

• 磁盘序列号、日志、通知、网络地址和其他服务器数据对已连接的 AI 客户端可见。请审查该客户端的数据处理政策。

官方参考资料

• Unraid API 概述

• 如何使用 Unraid API

• 以编程方式管理 API 密钥

• Unraid API 路线图和版本支持

• API v4.35.1 生成的 GraphQL schema

• Unraid 连接安全指南

• MCP TypeScript SDK stdio 指南

• MCP TypeScript SDK Streamable HTTP 指南

• Claude Code MCP 配置

• Codex MCP 配置

许可证

本项目根据 MIT License 授权。