unraid-mcp

# Unraid MCP <!-- mcp-name: tv.tootie/unraid-mcp --> [](https://pypi.org/project/unraid-mcp/) [](https://github.com/jmagar/unraid-mcp/pkgs/container/unraid-mcp) 基于 GraphQL 的 Unraid MCP 服务器，提供系统检查、管理操作、实时遥测和需要明确确认的破坏性操作。 ## 安装 插件位于 `plugins/unraid/`，通过 `uvx unraid-mcp`（已发布的 [PyPI 包](https://pypi.org/project/unraid-mcp/)）启动服务器，因此安装后无需本地检查。你需要在 `PATH` 中安装 [`uv`](https://docs.astral.sh/uv/)。 ### Claude Code（插件 + 市场） 将此仓库添加为市场，然后安装插件： ```text /plugin marketplace add jmagar/unraid-mcp /plugin install unraid-mcp@unraid-mcp ``` `marketplace add` 接受 `owner/repo` 简写（或完整的 git URL / 本地路径）。安装后，Claude Code 提示输入 **Unraid GraphQL API URL** 和 **Unraid API Key**（插件的 `userConfig`）；它们被传递给服务器并通过 SessionStart 钩子持久化到 `~/.unraid-mcp/.env`。 ### Codex（插件 + 市场） 仓库在 `.agents/plugins/marketplace.json` 处提供 Codex 市场清单： ```bash codex plugin marketplace add jmagar/unraid-mcp # 然后在 Codex 的 `/plugins` 视图中启用 `unraid-mcp@unraid-mcp` ``` Codex 不会将插件配置占位符扩展到 MCP 环境中，因此在启动 Codex 的 shell 中导出凭证（清单按名称转发它们）： ```bash export UNRAID_API_URL="https://tower.local/graphql" export UNRAID_API_KEY="your-api-key" ``` 或者，填充 `~/.unraid-mcp/.env`（运行 `uvx unraid-mcp setup`）；服务器会自动读取它。 ### Gemini CLI（扩展） 直接从仓库安装扩展（`gemini extensions install` 读取仓库根目录中的 `gemini-extension.json`）： ```bash gemini extensions install https://github.com/jmagar/unraid-mcp ``` Gemini 提示输入 `UNRAID_API_URL` 和 `UNRAID_API_KEY` 设置，并在安装时将它们导出到服务器环境中。 ### 直接使用 uvx 运行服务器 无需克隆即可运行已发布的软件包： ```bash export UNRAID_API_URL="https://tower.local/graphql" export UNRAID_API_KEY="your-api-key" uvx unraid-mcp ``` ### 本地开发 ```bash uv sync --dev uv run unraid-mcp-server ``` 等效入口点： ```bash uv run unraid-mcp uv run python -m unraid_mcp ``` ### Docker ```bash docker compose up -d ``` ### Claude Desktop 较新的 Claude Desktop 版本可能会在服务器在 Docker 中运行时拒绝原始 `streamable-http` URL 配置。通过 `mcp-remote` 代理连接 - 有关 macOS/Linux 和 Windows 配置片段，请参阅 [docs/mcp/CONNECT.md](docs/mcp/CONNECT.md#claude-desktop-via-mcp-remote-proxy)。 ## 配置 从 `.env.example` 创建 `.env`： ```bash just setup ``` ### 环境变量 | 变量 | 是否必需 | 默认值 | 描述 | | --- | --- | --- | --- | | `UNRAID_API_URL` | 是 | - | GraphQL 端点 URL，例如 `https://tower.local/graphql` | | `UNRAID_API_KEY` | 是 | - | Unraid API 密钥（参见下文） | | `UNRAID_MCP_TRANSPORT` | 否 | `streamable-http` | 传输方式：`streamable-http`、`stdio` 或旧版 `sse`（已弃用；将在 v3.0.0 中删除） | | `UNRAID_MCP_HOST` | 否 | 裸金属 `127.0.0.1`；Docker 设置为 `0.0.0.0` | HTTP 传输的绑定地址 | | `UNRAID_MCP_PORT` | 否 | `6970` | HTTP 传输的监听端口 | | `UNRAID_MCP_MAX_RESPONSE_BYTES` | 否 | `40000` | 最大序列化工具响应大小；超过响应预算的响应返回可解析的截断标记 | | `UNRAID_MCP_BEARER_TOKEN` | 条件 | - | HTTP 传输的静态 Bearer 令牌；如果未设置，则在首次启动时自动生成 | | `UNRAID_MCP_DISABLE_HTTP_AUTH` | 否 | `false` | 设置为 `true` 以跳过 Bearer 身份验证（在已经处理身份验证的反向代理后面使用） | | `UNRAID_MCP_TRUST_PROXY` | 条件 | `false` | 在禁用 HTTP 身份验证同时绑定非回环接口时需要 | | `UNRAID_MCP_GOOGLE_CLIENT_ID` | 否 | - | Google OAuth 客户端 ID；同时设置客户端 ID 和密钥替换 HTTP 传输的 Bearer 身份验证 | | `UNRAID_MCP_GOOGLE_CLIENT_SECRET` | 否 | - | Google OAuth 客户端密钥 | | `UNRAID_MCP_GOOGLE_BASE_URL` | 条件 | - | 公共服务器基准 URL，Google OAuth 启用时需要 | | `UNRAID_MCP_GOOGLE_REQUIRED_SCOPES` | 否 | `openid` + `userinfo.email` | 以逗号/空格分隔的 OAuth 范围 | | `UNRAID_MCP_GOOGLE_ALLOWED_EMAILS` | 条件 | - | 允许使用 MCP 服务器的已验证 Google 电子邮件 | | `UNRAID_MCP_GOOGLE_ALLOWED_DOMAINS` | 条件 | - | 允许使用 MCP 服务器的已验证 Google 电子邮件域 | | `UNRAID_MCP_GOOGLE_ALLOW_ANY_USER` | 否 | `false` | 显式允许任何已验证的 Google 帐户；仅适用于私有/受信任的部署 | | `UNRAID_MCP_GOOGLE_REDIRECT_PATH` | 否 | `/auth/callback` | Google Cloud 中配置的 OAuth 回调路径 | | `UNRAID_MCP_GOOGLE_JWT_SIGNING_KEY` | 条件 | - | 使用加密密钥启用重启后生存的加密令牌存储 | | `UNRAID_MCP_GOOGLE_ENCRYPTION_KEY` | 条件 | - | 用于加密 OAuth 令牌存储的 Fernet 密钥 | | `UNRAID_MCP_GOOGLE_STORAGE_DIR` | 否 | `~/.unraid-mcp/oauth-tokens` | 持久加密 OAuth 令牌的目录 | | `UNRAID_VERIFY_SSL` | 否 | `true` | 上游 Unraid API TLS 验证；也可以是 CA 包路径 | | `UNRAID_ALLOW_INSECURE_TLS` | 条件 | `false` | 当 `UNRAID_VERIFY_SSL=false` 时需要的第二个确认 | | `UNRAID_MCP_LOG_LEVEL` | 否 | `INFO` | 日志详细程度：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL` | | `UNRAID_MCP_LOG_FILE` | 否 | `unraid-mcp.log` | `logs/` 或 `/app/logs/` 下的日志文件名（在 Docker 中） | | `UNRAID_AUTO_START_SUBSCRIPTIONS` | 否 | `true` | 在首次资源/诊断访问时惰性初始化已启用的订阅 | | `UNRAID_MAX_RECONNECT_ATTEMPTS` | 否 | `10` | 最大 WebSocket 重新连接尝试次数 | | `UNRAID_AUTOSTART_LOG_PATH` | 否 | 自动检测 | 惰性初始化日志尾订阅的日志文件路径 | | `UNRAID_MCP_ENABLE_RAW_SUBSCRIPTION_PROBE` | 否 | `false` | 调试仅限原始上游帧在 `subscriptions/test_query`；数据敏感，共享部署永远不要使用 | | `UNRAID_SUBSCRIPTION_MAX_CONNECTIONS` | 否 | `3` | 每个进程的并发订阅启动握手（1..32） | | `UNRAID_SUBSCRIPTION_STARTUP_STAGGER_SECONDS` | 否 | `0.05` | 启动启动之间的延迟（0..10 秒） | | `UNRAID_SUBSCRIPTION_COLLECT_MAX_EVENTS` | 否 | `100` | 飞行中收集事件上限（1..10000；`limit` 可能会降低它） | | `UNRAID_SUBSCRIPTION_COLLECT_MAX_BYTES` | 否 | `1048576` | 飞行中序列化收集字节上限；响应预算可能会降低它 | | `UNRAID_SUBSCRIPTION_COLLECT_MAX_SECONDS` | 否 | `30` | 最大 `collect_for` 时长；可配置高达 300 秒 | | `UNRAID_SUBSCRIPTION_CACHE_MAX_AGE_SECONDS` | 否 | `300` | 最大可用缓存年龄（秒）；可配置高达 86400 | | `UNRAID_SUBSCRIPTION_TIMEOUT_MAX_SECONDS` | 否 | `60` | 最大每次调用的 WebSocket 超时时间；可配置高达 300 秒 | | `UNRAID_CREDENTIALS_DIR` | 否 | `~/.unraid-mcp` | 重写凭证目录 | | `DOCKER_NETWORK` | 否 | - | 要加入的外部 Docker 网络；留空以使用默认桥接网络 | | `PGID` | 否 | `1000` | 容器进程 GID | | `PUID` | 否 | `1000` | 容器进程 UID | 有关完整参考，包括 OAuth 持久性和 `.env` 加载顺序，请参阅 [docs/mcp/ENV.md](docs/mcp/ENV.md)、[docs/CONFIG.md](docs/CONFIG.md) 和 [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md)。 ### 如何找到 UNRAID_API_KEY 1. 打开 Unraid Web UI。 2. 转到 **设置 → 管理访问 → API 密钥**。 3. 创建新密钥或复制现有密钥。 4. 将值粘贴到 `UNRAID_API_KEY`。 ### UNRAID_API_KEY 与 UNRAID_MCP_BEARER_TOKEN 这是两个独立的凭证，具有不同的用途： - `UNRAID_API_KEY` — 对 **Unraid GraphQL API** 进行身份验证。每个 GraphQL 请求都携带此密钥作为标头。从 Unraid Web UI 获取。 - `UNRAID_MCP_BEARER_TOKEN` — 对 **MCP 客户端**（Claude Code、Claude Desktop 等）进行身份验证 **此 MCP 服务器**。客户端必须在每个 HTTP 请求上发送 `Authorization: Bearer <token>`。使用 `openssl rand -hex 32` 或 `just gen-token` 生成。 ### UNRAID_MCP_DISABLE_HTTP_AUTH 将此设置为 `true` 时，如果反向代理（nginx、Caddy、Traefik、SWAG）已经在请求到达 MCP 服务器之前处理身份验证，则禁用内置检查。启用此标志时，请勿将服务器直接暴露给不受信任的网络。 如果身份验证被禁用并且 `UNRAID_MCP_HOST` 绑定非回环接口，服务器还需要 `UNRAID_MCP_TRUST_PROXY=true` 作为明确的断言，即受信任的前置网关强制执行身份验证。 ### Google OAuth 用于 HTTP 传输 同时设置 `UNRAID_MCP_GOOGLE_CLIENT_ID` 和 `UNRAID_MCP_GOOGLE_CLIENT_SECRET` 以用 Google OAuth 替换静态 Bearer 身份验证。OAuth 需要 `UNRAID_MCP_GOOGLE_BASE_URL` 和至少一个授权允许列表条目（`UNRAID_MCP_GOOGLE_ALLOWED_EMAILS` 或 `UNRAID_MCP_GOOGLE_ALLOWED_DOMAINS`），除非显式设置 `UNRAID_MCP_GOOGLE_ALLOW_ANY_USER=true`。Google OAuth 和 `UNRAID_MCP_DISABLE_HTTP_AUTH=true` 是互斥的。 ### 传输模式 - `streamable-http` — 默认；公开 HTTP 端点，需要 Bearer 令牌，除非禁用身份验证 - `stdio` — Claude Code 本地插件的子进程模式；不需要 Bearer 令牌 - `sse` — 旧版 Server-Sent Events；已弃用，发出警告，将在 v3.0.0 中删除。迁移到可流式 HTTP 或在它前面放置兼容性代理。 凭证文件按优先级加载：`~/.unraid-mcp/.env` 首先，然后是项目 `.env` 作为回退。 ## 概述 服务器将 MCP 工具调用转换为 Unraid GraphQL 查询和变体操作，支持 HTTP 和 WebSocket。所有操作共享一个 `unraid` 工具，由 `action` + `subaction` 路由。实时遥测使用 WebSocket 订阅，从 Unraid API 流式传输实时数据。 ## 本仓库提供的内容 ``` unraid-mcp/ ├── unraid_mcp/ # 服务器、GraphQL 客户端、订阅、配置、工具处理程序 ├── plugins/ │ └── unraid/ # 可分发的插件/扩展（每个客户端一个） │ ├── .claude-plugin/ # Claude Code 插件清单（plugin.json）+ README │ ├── .codex-plugin/ # Codex 插件清单（plugin.json） │ ├── .mcp.json # 共享 MCP 服务器定义（Claude）- 运行 `uvx unraid-mcp` │ ├── hooks/ # SessionStart / ConfigChange 钩子（hooks.json） │ ├── scripts/ # 插件运行时钩子脚本（plugin-setup.sh） │ └── skills/unraid/ # 面向客户端的技能文档、引用和帮助程序 ├── gemini-extension.json # Gemini CLI 扩展清单（仓库根目录，用于 git-URL 安装） ├── .claude-plugin/ │ └── marketplace.json # Claude Code 市场清单（列出上面的插件） ├── .agents/plugins/ │ └── marketplace.json # Codex 市场清单 ├── scripts/ # 仓库维护脚本（CI、版本同步、验证） ├── docs/ # 身份验证、破坏性操作和发布引用 ├── docker-compose.yaml, Dockerfile, entrypoint.sh # 容器部署 └── tests/ # 单元、安全、模式、HTTP 层和实时覆盖测试 ``` ## 工具 服务器注册一个 **单个 `unraid` 工具**。每个操作都通过 `unraid(action=..., subaction=...)` 访问。订阅诊断和 Markdown 参考本身就是该工具的操作（`subscriptions` 和 `help`）。 ### 工具索引 | 工具 | 用途 | | --- | --- | | `unraid` | 统一的操作/子操作路由器，用于所有操作（包括 `help` 和 `subscriptions` 诊断） | ### `unraid` — 操作组 所有操作都通过一个工具进行。选择一个 `action`，然后在其中选择一个 `subaction`。 #### `system` — 25 个子操作 服务器信息、指标、网络和 UPS。 | 子操作 | 描述 | 必需参数 | | --- | --- | --- | | `overview` | OS、CPU、内存布局、版本、机 ID | - | | `array` | 数组状态、容量、磁盘健康摘要 | - | | `network` | 访问 URL、HTTP/HTTPS 端口、LAN/WAN IP 地址 | - | | `registration` | 许可证类型、密钥文件、过期日期 | - | | `variables` | 完整的 Unraid 变量集（时区、共享等） | - | | `metrics` | 当前 CPU% 和内存使用率 | - | | `network_metrics` | 当前网络吞吐量指标来自 `metrics.network` | - | | `services` | 运行的服务名称、在线状态、版本 | - | | `display` | 当前 UI 主题名称 | - | | `display_details` | 直接 `display` 根元数据：案例、主题、温度显示设置、值、本地化 | - | | `config` | 配置有效性和错误状态 | - | | `online` | 布尔可达性检查 | - | | `owner` | 所有者用户名、头像、配置文件 URL | - | | `settings` | 统一设置键/值映射 | - | | `server` | 单个调用摘要：主机名、运行时间、Unraid 版本、数组状态 | - | | `stop_array` | 停止 Unraid 数组 | - | 是 | | `add_disk` | 将磁盘添加到数组 | `disk_id`；可选 `slot` | - | | `remove_disk` | 从数组中删除磁盘（必须停止数组） | `disk_id`, `confirm=True` | 是 | | `mount_disk` | 挂载数组磁盘 | `disk_id` | - | | `unmount_disk` | 卸载数组磁盘 | `disk_id` | - | | `clear_disk_stats` | 清除磁盘的 I/O 统计信息（不可逆） | `disk_id`, `confirm=True` | 是 | #### `health` — 4 个子操作 连接和系统健康诊断。 | 子操作 | 描述 | 必需参数 | | --- | --- | --- | | `check` | 综合健康状况：API 延迟、数组状态、警报、Docker 容器摘要 | - | | `test_connection` | ping Unraid API 并返回毫秒延迟 | - | | `diagnose` | 订阅系统状态、错误计数、重新连接状态 | - | | `setup` | 报告凭证状态并打印插件/`.env` 设置说明 | - | #### `array` — 14 个子操作 奇偶校验检查和数组磁盘操作。破坏性子操作标记为 *。 | 子操作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `parity_status` | 当前奇偶校验检查进度、速度、错误 | - | - | | `parity_history` | 过去的奇偶校验检查结果 | - | - | | `assignable_disks` | 尚未在数组中的物理磁盘（与 `add_disk` 配对） | - | - | | `parity_start` | 启动奇偶校验检查 | `correct` (bool) | - | | `parity_pause` | 暂停正在运行的奇偶校验检查 | - | - | | `parity_resume` | 恢复暂停的奇偶校验检查 | - | - | | `parity_cancel` | 取消正在运行的奇偶校验检查 | - | - | | `start_array` | 启动 Unraid 数组 | - | - | | `stop_array` | 停止 Unraid 数组 | `confirm=True` | 是 | | `add_disk` | 将磁盘添加到数组 | `disk_id`；可选 `slot` | - | | `remove_disk` | 从数组中删除磁盘（必须停止数组） | `disk_id`, `confirm=True` | 是 | | `mount_disk` | 挂载数组磁盘 | `disk_id` | - | | `unmount_disk` | 卸载数组磁盘 | `disk_id` | - | | `clear_disk_stats` | 清除磁盘的 I/O 统计信息（不可逆） | `disk_id`, `confirm=True` | 是 | #### `disk` — 6 个子操作 共享、物理磁盘、日志文件和闪存备份。破坏性子操作标记为 *。 | 子操作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `shares` | 所有用户共享信息，包含大小、分配设置、LUKS 状态 | - | - | | `disks` | 物理磁盘列表（ID、设备、名称） | - | - | | `disk_details` | 单个磁盘：序列号、大小、温度 | `disk_id` | - | | `log_files` | 列出可用的日志文件（名称、路径、大小、修改时间） | - | - | | `logs` | 读取日志文件内容，带有行范围 | `log_path`；可选 `tail_lines`（默认为 100，最大 10000） | - | | `flash_backup` | 启动 rclone 将闪存驱动器备份到远程 | `remote_name`, `source_path`（必须以 `/boot` 开头）、`destination_path`、`confirm=True` | 是 | **`flash_backup` 详细信息：** 调用 Unraid `initiateFlashBackup` GraphQL 变体，该变体触发从闪存驱动器到配置的 rclone 远程的 rclone 复制。如果目标远程上已存在目标，则覆盖它。返回 `{ status, jobId }`。要恢复：使用 rclone 将备份复制回闪存驱动器，或提取单个配置文件。先使用 `rclone/create_remote` 配置 rclone 远程。 #### `docker` — 26 子动作 容器生命周期，镜像更新，模板/摘要维护，组织文件夹和网络检查。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `list` | 所有容器：ID，名称，镜像，状态，状态，自动启动 | — | — | | `details` | 完整的容器详情：端口，挂载，标签，网络设置 | `container_id` | — | | `logs` | 不通过 Unraid GraphQL API 提供 - 返回使用 `docker logs` 命令的指导 | `container_id` | — | | `ports` | 所有运行容器上的主机端口绑定，按 `(host_port, protocol)` 排序。 | — | — | | `start` | 启动容器 | `container_id` | — | | `stop` | 停止容器 | `container_id` | — | | `restart` | 停止然后启动容器（顺序停止和启动） | `container_id` | — | | `unpause` | 取消暂停容器 | `container_id` | — | | `remove_container` | 删除容器（可选地通过 `with_image` 删除其镜像） | `container_id`, `confirm=True` | * | | `update_container` | 对单个容器应用待处理的镜像更新 | `container_id` | — | | `update_containers` | 对多个容器应用镜像更新 | `container_ids` | — | | `update_all_containers` | 应用所有待处理的容器镜像更新 | — | — | | `update_autostart` | 设置容器自动启动配置 | `autostart_entries` (`[{id, autoStart, wait?}]`) | — | | `refresh_digests` | 刷新镜像摘要（重新检查更新） | — | — | | `sync_template_paths` | 同步 Docker 模板路径 | — | — | | `reset_template_mappings` | 重置模板路径映射为默认值 | `confirm=True` | * | | `create_folder` | 创建组织文件夹 | `organizer_input` (`{name, …}`) | — | | `create_folder_with_items` | 创建包含项目的目录 | `organizer_input` | — | | `rename_folder` | 重命名目录 | `organizer_input` (`{folderId, newName}`) | — | | `set_folder_children` | 设置目录的子项 | `organizer_input` (`{childrenIds, …}`) | — | | `delete_entries` | 删除组织条目 | `organizer_input` (`{entryIds}`), `confirm=True` | * | | `move_entries_to_folder` | 将条目移动到目录中 | `organizer_input` | — | | `move_items_to_position` | 将项目移动到某个位置 | `organizer_input` | — | | `update_view_preferences` | 更新组织视图偏好 | `organizer_input` (`{prefs, …}`) | — | | `networks` | 所有 Docker 网络：ID，名称，驱动程序，范围 | — | — | | `network_details` | 具有 IPv6、容器、选项、标签的单个网络 | `network_id` | — | 容器标识符接受完整 ID、短 ID 前缀、确切名称或无歧义名称前缀。容器突变需要确切名称或完整 ID。组织子动作从 `organizer_input` 字典中读取其字段。 #### `vm` — 9 子动作 虚拟机生命周期。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `list` | 所有虚拟机：ID，名称，状态，UUID | — | — | | `details` | 单个虚拟机详情 | `vm_id` | — | | `start` | 启动虚拟机 | `vm_id` | — | | `stop` | 正常停止虚拟机 | `vm_id` | — | | `pause` | 暂停运行的虚拟机 | `vm_id` | — | | `resume` | 恢复暂停的虚拟机 | `vm_id` | — | | `reboot` | 重启虚拟机 | `vm_id` | — | | `force_stop` | 硬关机虚拟机（可能导致数据丢失） | `vm_id`, `confirm=True` | * | | `reset` | 硬重置虚拟机而不正常关闭 | `vm_id`, `confirm=True` | * | `vm_id` 接受 UUID、前缀 ID 或虚拟机名称。 #### `notification` — 13 子动作 系统通知 CRUD。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `overview` | 按重要性（INFO/WARNING/ALERT）显示未读和存档计数 | — | — | | `list` | 分页通知列表 | `list_type` (UNREAD 或 ARCHIVE，默认为 UNREAD)；可选 `importance`、`offset`、`limit` | — | | `create` | 创建通知 | `title` (≤200)、 `subject` (≤500)、 `description` (≤2000)、 `importance` (INFO/WARNING/ALERT) | — | | `notify_if_unique` | 仅当不存在相同通知时创建通知 | `title`、`subject`、`description`、`importance` | — | | `archive` | 存档单个通知 | `notification_id` | — | | `mark_unread` | 将存档通知移回未读 | `notification_id` | — | | `recalculate` | 重新计算概览计数 | — | — | | `archive_all` | 存档所有未读通知 | 可选 `importance` 进行过滤 | — | | `archive_many` | 通过 ID 存档特定通知 | `notification_ids` (列表) | — | | `unarchive_many` | 通过 ID 取消存档特定通知 | `notification_ids` (列表) | — | | `unarchive_all` | 将所有存档通知移回未读 | 可选 `importance` 进行过滤 | — | | `delete` | 永久删除单个通知 | `notification_id`、`notification_type`、`confirm=True` | * | | `delete_archived` | 永久删除所有存档通知 | `confirm=True` | * | #### `key` — 13 子动作 API 密钥和权限管理。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `list` | 所有具有角色和权限的 API 密钥 | — | — | | `get` | 单个 API 密钥详情 | `key_id` | — | | `possible_roles` | 所有可分配角色 | — | — | | `possible_permissions` | 所有可授予的资源/操作权限 | — | — | | `permissions_for_roles` | 给定角色的隐含权限 | `roles` | — | | `preview_permissions` | 角色和/或权限的有效权限 | `roles` 和/或 `permissions_input` (`[{resource, actions}]`) | — | | `auth_actions` | 所有可用的身份验证操作 | — | — | | `creation_form_schema` | API 密钥创建的 JSON 模式表单 | — | — | | `create` | 创建 API 密钥 | `name`；可选 `roles`、`permissions` | — | | `update` | 更新名称、角色或权限 | `key_id`；可选 `name`、`roles`、`permissions` | — | | `delete` | 删除 API 密钥（立即撤销访问权限） | `key_id`、`confirm=True` | * | | `add_role` | 向现有密钥添加角色 | `key_id`、`roles`（使用第一个元素） | — | | `remove_role` | 从现有密钥中删除角色 | `key_id`、`roles`（使用第一个元素） | — | #### `plugin` — 8 子动作 Unraid 插件管理和异步安装。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `list` | 所有已安装插件及其版本和模块标志 | — | — | | `installed_unraid` | 原始已安装 `.plg` 文件名 | — | — | | `install_operations` | 列出异步插件安装操作 | — | — | | `install_operation` | 单个安装操作的状态 | `operation_id` | — | | `add` | 通过名称安装插件 | `names` (列表)；可选 `bundled`、`restart` | — | | `remove` | 通过名称卸载插件（无法重新安装） | `names` (列表)、`confirm=True` | * | | `install` | 异步安装 `.plg` URL — 以 root 权限运行代码（通过 `install_operation` 轮询） | `url`、`confirm=True`；可选 `plugin_name`、`forced` | * | | `install_language` | 异步安装语言包 — 以 root 权限运行代码 | `url`、`confirm=True` | * | #### `rclone` — 4 子动作 云存储远程管理。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `list_remotes` | 所有配置的 rclone 远程设备及其类型和参数 | — | — | | `config_form` | 提供程序类型的配置表单模式 | 可选 `provider_type` | — | | `create_remote` | 创建新的 rclone 远程设备 | `name`、`provider_type`、`config_data`（字符串/数字/布尔值的字典；最多 50 个键） | — | | `delete_remote` | 删除 rclone 远程配置（不会删除远程数据） | `name`、`confirm=True` | * | #### `setting` — 6 子动作 系统设置、UPS、SSH、时间和服务器身份。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `update` | 更新系统设置（JSON 键/值输入） | `settings_input`（字典；最多 100 个键，仅标量值） | — | | `configure_ups` | 覆盖 UPS 监控配置 | `ups_config`（字典）、`confirm=True` | * | | `update_ssh` | 更新 SSH 守护进程设置（可能切断 shell 访问权限） | `config_input` (`{enabled, port}`)、`confirm=True` | * | | `update_temperature` | 更新温度传感器配置 | `config_input` | — | | `update_system_time` | 更新时区 / NTP / 手动时间 — 可能使 TLS 证书失效 | `config_input`、`confirm=True` | * | | `update_server_identity` | 更新服务器名称、注释和型号 | `name`；可选 `comment`、`sys_model` | — | #### `connect` — 8 子动作 Unraid Connect / 远程访问状态和控制。破坏性子动作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `remote_access` | 当前远程访问设置（类型、转发、端口） | — | — | | `cloud` | Unraid Connect / 云状态（中继、微图、密钥有效性） | — | — | | `status` | 直接 `connect` 根状态：动态远程访问和设置模式；省略设置值 | — | — | | `update_api_settings` | 更新 Connect API 设置（影响互联网可访问性） | `connect_input` (`{accessType?, forwardType?, port?}`)、`confirm=True` | * | | `sign_in` | 将服务器登录到 Unraid Connect — 在云中注册 | `connect_input` (`{apiKey, userInfo?}`)、`confirm=True` | * | | `sign_out` | 将服务器注销 Unraid Connect | `confirm=True` | * | | `setup_remote_access` | 配置远程访问 — 可以将服务器暴露在互联网上 | `connect_input`、`confirm=True` | * | | `enable_dynamic_remote_access` | 切换动态远程访问 | `connect_input` (`{url, enabled}`)、`confirm=True` | * | #### `customization` — 6 子动作 UI 主题、语言和 SSO 状态。 | 子动作 | 描述 | 必需参数 | | --- | --- | --- | | `public_theme` | 公开主题（也是服务器的当前主题） | — | | `is_initial_setup` | 是否是全新安装 (`isFreshInstall`) | — | | `sso_enabled` | 是否启用 SSO | — | | `details` | 直接 `customization` 根 onboarding/语言详情；激活码值省略 | — | | `set_theme` | 设置活动 UI 主题 | `theme_name` | | `set_locale` | 设置 UI 语言 | `locale` | #### `oidc` — 5 子动作 OpenID Connect / SSO 提供程序管理。 | 子动作 | 描述 | 必需参数 | | --- | --- | --- | | `providers` | 所有 OIDC 提供程序，包含客户端 ID、作用域、身份验证规则 | — | | `provider` | 单个提供程序详情 | `provider_id` | | `configuration` | OIDC 配置，包含默认允许的来源 | — | | `public_providers` | 公共提供程序列表（按钮文本、图标、样式） | — | | `validate_session` | 验证 OIDC 会话令牌 | `token` | #### `onboarding` — 11 子动作 首次启动 / onboarding 状态和内部启动上下文。这些操作设置状态，很少在配置的服务器上需要；危险操作标记为 *。 | 子动作 | 描述 | 必需参数 | 破坏性 | | --- | --- | --- | --- | | `internal_boot_context` | 内部启动 / 首次启动上下文 | — | — | | `complete` | 标记 onboarding 完成 | — | — | | `open` | 打开 onboarding 流 | — | — | | `close` | 关闭 onboarding 流 | — | — | | `resume` | 恢复 onboarding | — | — | | `bypass` | 跳过 onboarding | — | — | | `reset` | 重置 onboarding/setup 状态 | `confirm=True` | * | | `set_override` | 设置 onboarding 重载 | `onboarding_input` | — | | `clear_override` | 清除 onboarding 重载 | — | — | | `refresh_internal_boot_context` | 重新计算内部启动上下文 | — | — | | `create_internal_boot_pool` | 创建内部启动池 — 格式化设备，可能重启 | `onboarding_input`、`confirm=True` | * | #### `user` — 1 子动作 | 子动作 | 描述 | 必需参数 | | --- | --- | --- | | `me` | 身份验证用户：ID、名称、描述、角色 | — | #### `live` — 17 子动作（WebSocket 订阅） `live` 操作组从 Unraid GraphQL API 的活动 WebSocket 订阅中读取。代替发出 HTTP 查询，它打开一个 `graphql-transport-ws` 连接，并等待一个快照或在窗口内收集事件。 两种交付模式： - **快照** (`SNAPSHOT_ACTIONS`)：打开订阅并在 `timeout` 秒内返回接收到的第一个消息。对于事件驱动的子动作（`parity_progress`、`ups_status`、`notifications_overview`、`notifications_warnings`、`owner`、`server_status`、`display`），超时意味着没有最近的状态更改 — 不是错误。 - **收集** (`COLLECT_ACTIONS`)：打开订阅并保留事件，直到 `collect_for` 过期、流完成或达到有效事件/字节预算。迭代器在边界处立即关闭；保留有界限，而不仅在响应被塑形时。 | 子动作 | 模式 | 描述 | 必需参数 | | --- | --- | --- | --- | | `cpu` | 快照 | CPU 利用率：总百分比和每核分解 | — | | `memory` | 快照 | 内存：总内存、已用内存、空闲内存、交换内存、百分比 | — | | `cpu_telemetry` | 快照 | CPU 功耗和温度 | — | | `array_state` | 快照 | 数组状态、容量、奇偶校验检查状态 | — | | `parity_progress` | 快照（事件驱动） | 奇偶校验检查进度、速度、错误 | — | | `ups_status` | 快照（事件驱动） | UPS 电池、充电、运行时、负载 | — | | `notifications_overview` | 快照（事件驱动） | 按重要性显示通知计数 | — | | `notifications_warnings` | 快照（事件驱动） | 警告/警报动态（过滤） | — | | `owner` | 快照（事件驱动） | 所有者配置文件更改 | — | | `server_status` | 快照（事件驱动） | 服务器注册和连接性 | — | | `display` | 快照（事件驱动） | 主题/显示更改 | — | | `docker_container_stats` | 快照 | 每个容器的 CPU/内存/IO 统计信息 | — | | `temperature` | 快照 | 温度传感器读数 | — | | `network_metrics` | 快照 | 网络吞吐量指标 | — | | `log_tail` | 收集 | 流日志文件行 | `path`（必须以 `/var/log/` 或 `/boot/logs/` 开头） | | `notification_feed` | 收集 | 流入通知 | — | | `plugin_install_updates` | 收集 | 流式插件安装进度事件 | `operation_id`（必需） | `live` 的可选参数： - `collect_for`（浮点数，默认 `5.0`）— 大于 0 且最多 `UNRAID_SUBSCRIPTION_COLLECT_MAX_SECONDS`（默认 30 秒） - `timeout`（浮点数，默认 `10.0`）— 大于 0 且最多 `UNRAID_SUBSCRIPTION_TIMEOUT_MAX_SECONDS`（默认 60 秒） 收集最多保留 `min(positive limit, UNRAID_SUBSCRIPTION_COLLECT_MAX_EVENTS)` 事件（默认 100）以及最多 `UNRAID_SUBSCRIPTION_COLLECT_MAX_BYTES`（默认 1 MiB）和配置的 MCP 响应预算的较小值（默认 20 KiB）。响应包括 `page.returned`、`page.total`、 `page.truncated` 和一个提示，当响应上限截断结果时。这些响应字段 与前面的流式传输限制不同。 #### `subscriptions` — 2 子动作（WebSocket 诊断） Unraid live 订阅系统的诊断信息。在 `live` 子动作 无数据返回时很有用。 | 子动作 | 描述 | 必需参数 | | --- | --- | --- | | `diagnose` | 完整的诊断转储：自动启动状态、重新连接配置、每个订阅状态（活动、最后错误、收到的数据）、错误计数和故障排除建议 | — | | `test_query` | 直接通过 WebSocket 将原始 GraphQL 订阅字符串发送到模式/字段问题进行调试 | `subscription_query` | `test_query` 验证查询 — 它必须是 `subscription` 操作 针对一个允许的字段之一（`logFile`、`containerStats`、`cpu`、 `memory`、`array`、`network`、`docker`、`vm`、`systemMetricsTemperature`、 `displaySubscription`、`notificationsWarningsAndAlerts`、 `pluginInstallUpdates`）；不接受突变/查询关键字。 ``` unraid(action="subscriptions", subaction="diagnose") unraid(action="subscriptions", subaction="test_query", subscription_query="subscription { cpu { used idle system } }") ``` #### `help` — Markdown 参考 `unraid(action="help")` 以 Markdown 格式返回此操作/子操作参考。 ### 破坏性操作摘要 所有破坏性操作都需要 `confirm=True`。省略它或传递 `confirm=False` 会在任何网络请求之前引发 `ToolError`。 > 共 26 个破坏性子操作；`plugin` `install` / `install_language` 共享下面的一行。 | 操作 | 子操作 | 备注 | | --- | --- | --- | | `array` | `stop_array` | 卸载共享；先停止容器和虚拟机 | | `array` | `remove_disk` | 数组必须先停止 | | `array` | `clear_disk_stats` | I/O 统计数据将被永久擦除 | | `vm` | `force_stop` | 硬关机；未保存的数据可能会丢失 | | `vm` | `reset` | 硬重置；未保存的数据可能会丢失 | | `notification` | `delete` | 永久删除；需要 `notification_type` | | `notification` | `delete_archived` | 清除所有已存档的通知 | | `rclone` | `delete_remote` | 仅删除配置；不会删除远程数据 | | `key` | `delete` | 立即吊销所有使用该密钥的客户端 | | `disk` | `flash_backup` | 覆盖目标；配置专用远程 | | `setting` | `configure_ups` | 覆盖 UPS 守护进程配置 | | `setting` | `update_ssh` | 可能会切断远程 shell 访问（禁用 SSH / 更改端口） | | `setting` | `update_system_time` | 时钟更改可能会使 TLS 证书失效 / 破坏时间敏感的服务 | | `plugin` | `remove` | 无法撤销，除非重新安装 | | `plugin` | `install` / `install_language` | 从 URL 获取并以 root 运行 `.plg` | | `connect` | `sign_in` | 将服务器注册到 Unraid Connect 云 | | `connect` | `update_api_settings` | 更改远程访问姿态 / 互联网可达性 | | `docker` | `remove_container` | 删除容器（和可选的镜像） | | `docker` | `reset_template_mappings` | 将 Docker 模板路径映射重置为默认值 | | `docker` | `delete_entries` | 删除 Docker 组织者条目 | | `connect` | `sign_out` | 将服务器注销出 Unraid Connect | | `connect` | `setup_remote_access` | 重新配置远程访问；可能会暴露服务器 | | `connect` | `enable_dynamic_remote_access` | 切换动态远程访问 | | `onboarding` | `reset` | 重置 onboarding/setup 状态 | | `onboarding` | `create_internal_boot_pool` | 格式化设备并可能重启服务器 | ### 工具参数参考 | 参数 | 类型 | 使用者 | | --- | --- | --- | | `action` | str | 所有 | | `subaction` | str | 所有 | | `confirm` | bool（默认 `False`） | 破坏性子操作 | | `device_id` | str | `system/ups_device` | | `disk_id` | str | `array`，`disk` | | `correct` | bool | `array/parity_start` | | `slot` | int | `array/add_disk` | | `log_path` | str | `disk/logs` | | `tail_lines` | int（默认 100，最大 10000） | `disk/logs` | | `remote_name` | str | `disk/flash_backup` | | `source_path` | str | `disk/flash_backup` | | `destination_path` | str | `disk/flash_backup` | | `backup_options` | dict | `disk/flash_backup` | | `container_id` | str | `docker` 变异和 `details` | | `container_ids` | list[str] | `docker/update_containers` | | `with_image` | bool（默认 `False`） | `docker/remove_container` | | `autostart_entries` | list[dict] | `docker/update_autostart` | | `organizer_input` | dict | `docker` 组织者子操作 | | `network_id` | str | `docker/network_details` | | `vm_id` | str | `vm`（除 `list` 外所有） | | `notification_id` | str | `notification/archive`，`mark_unread`，`delete` | | `notification_ids` | list[str] | `notification/archive_many`，`unarchive_many` | | `notification_type` | str（UNREAD/ARCHIVE） | `notification/delete` | | `importance` | str（INFO/WARNING/ALERT） | `notification` 过滤和创建 | | `list_type` | str（UNREAD/ARCHIVE，默认 UNREAD） | `notification/list` | | `title` | str（≤200） | `notification/create` | | `subject` | str（≤500） | `notification/create` | | `description` | str（≤2000） | `notification/create` | | `offset` | int（默认 0） | `notification/list` | | `limit` | int（默认 20） | `notification/list` | | `key_id` | str | `key` 子操作 | | `name` | str | `key/create`，`key/update`，`rclone` | | `roles` | list[str] | `key` 子操作 | | `permissions` | list[str] | `key` 子操作 | | `permissions_input` | list[dict] | `key/preview_permissions` | | `names` | list[str] | `plugin/add`，`plugin/remove` | | `bundled` | bool（默认 `False`） | `plugin/add`，`plugin/remove` | | `restart` | bool（默认 `True`） | `plugin/add`，`plugin/remove` | | `url` | str | `plugin/install`，`plugin/install_language` | | `plugin_name` | str | `plugin/install` | | `forced` | bool（默认 `False`） | `plugin/install` | | `operation_id` | str | `plugin/install_operation` | | `provider_type` | str | `rclone/config_form`，`rclone/create_remote` | | `config_data` | dict | `rclone/create_remote` | | `settings_input` | dict | `setting/update` | | `ups_config` | dict | `setting/configure_ups` | | `config_input` | dict | `setting/update_ssh`，`update_temperature`，`update_system_time` | | `comment` | str | `setting/update_server_identity` | | `sys_model` | str | `setting/update_server_identity` | | `connect_input` | dict | `connect` 变异 | | `onboarding_input` | dict | `onboarding/set_override`，`create_internal_boot_pool` | | `theme_name` | str | `customization/set_theme` | | `locale` | str | `customization/set_locale` | | `provider_id` | str | `oidc/provider` | | `token` | str | `oidc/validate_session` | | `path` | str | `live/log_tail` | | `subscription_query` | str | `subscriptions/test_query` | | `collect_for` | float（默认 `5.0`） | `live` 收集模式子操作 | | `timeout` | float（默认 `10.0`） | `live` 所有子操作 | ## 用例 ### 系统检查 ```python unraid(action="system", subaction="overview") unraid(action="system", subaction="array") unraid(action="live", subaction="cpu") unraid(action="live", subaction="memory") unraid(action="health", subaction="check") ``` ### 校验工作流 ```python unraid(action="array", subaction="parity_status") unraid(action="array", subaction="parity_start", correct=True) # 修正通过 unraid(action="array", subaction="parity_start", correct=False) # 只读通过 unraid(action="live", subaction="parity_progress", timeout=15.0) unraid(action="array", subaction="parity_pause") unraid(action="array", subaction="parity_resume") unraid(action="array", subaction="parity_cancel") unraid(action="array", subaction="parity_history") ``` ### Docker 管理 ```python unraid(action="docker", subaction="list") unraid(action="docker", subaction="start", container_id="plex") unraid(action="docker", subaction="stop", container_id="plex") unraid(action="docker", subaction="restart", container_id="plex") unraid(action="docker", subaction="details", container_id="plex") unraid(action="docker", subaction="networks") ``` ### 虚拟机操作 ```python unraid(action="vm", subaction="list") unraid(action="vm", subaction="start", vm_id="windows11") unraid(action="vm", subaction="stop", vm_id="windows11") unraid(action="vm", subaction="pause", vm_id="windows11") unraid(action="vm", subaction="resume", vm_id="windows11") unraid(action="vm", subaction="force_stop", vm_id="windows11", confirm=True) ``` ### 日志跟踪 ```python unraid(action="live", subaction="log_tail", path="/var/log/syslog", collect_for=5.0) unraid(action="disk", subaction="logs", log_path="/var/log/syslog", tail_lines=200) unraid(action="disk", subaction="log_files") ``` ### 通知 ```python unraid(action="notification", subaction="overview") unraid(action="notification", subaction="list", list_type="UNREAD", limit=10) unraid(action="notification", subaction="list", list_type="UNREAD", importance="ALERT") unraid( action="notification", subaction="create", title="Test", subject="Test notification", description="Created via MCP", importance="INFO", ) unraid(action="live", subaction="notification_feed", collect_for=10.0) ``` ### 闪存备份 ```python unraid(action="rclone", subaction="list_remotes") unraid( action="disk", subaction="flash_backup", remote_name="my-backup-remote", source_path="/boot", destination_path="/flash-backups/tower", confirm=True, # 覆盖目标 ) ``` ## 开发命令 | 命令 | 效果 | | --- | --- | | `just dev` | 通过 `uv run python -m unraid_mcp` 启动开发服务器 | | `just test` | 运行完整测试套件 | | `just lint` | 运行 ruff 静态分析工具 | | `just fmt` | 运行 ruff 格式化工具 | | `just typecheck` | 运行 `ty` 类型检查器 (`uv run ty check unraid_mcp/`, 匹配 CI) | | `just test-live` | 运行实时集成测试（需要运行的 Unraid 服务器） | | `just up` | 通过 Docker Compose 启动 | | `just down` | 停止 Docker Compose 容器 | | `just logs` | 跟踪 Docker Compose 容器日志 | | `just health` | 检查 `/health` 端点 | | `just gen-token` | 生成安全的随机 Bearer 令牌 | | `just check-contract` | Docker 安全、 baked-env 和 ignore-file 检查 | | `just setup` | 如果缺少，从 `.env.example` 创建 `.env` | | `just clean` | 删除构建工件和缓存 | ## 验证 ```bash just lint just typecheck just test ``` 对于 stdio MCP 烟雾测试： ```bash uv run unraid-mcp-server ``` 对于 `just up` 后的 HTTP 健康检查： ```bash just health ``` `tests/safety/` 中的自动化安全测试验证每个破坏性操作在没有 `confirm=True` 的情况下都会引发 `ToolError`，并且在这种情况下不会有 GraphQL 请求到达网络层。 ## GraphQL 模式概述 服务器针对 Unraid GraphQL API 发出查询和变异。关键查询根： | 根 | 使用者 | | --- | --- | | `info` | `system/overview`，`system/display`，健康检查 | | `array` | `system/array`，`array/*` | | `vars` | `system/network`，`system/variables` | | `metrics` | `system/metrics` | | `services` | `system/services` | | `display` | `system/display_details`（直接安全根） | | `servers` | `system/servers`，`system/network` | | `network` | `system/network_access_urls`（直接安全根） | | `server` | `system/server_details`（直接安全根；省略 API 密钥） | | `registration` | `system/registration` | | `online` | `system/online`，`health/test_connection` | | `owner` | `system/owner` | | `settings` | `system/settings` | | `flash` | `system/flash` | | `upsDevices` / `upsDeviceById` | `system/ups_devices`，`system/ups_device` | | `upsConfiguration` | `system/ups_config` | | `parityHistory` | `array/parity_history` | | `disk` / `disks` | `disk/disk_details`，`disk/disks` | | `shares` | `disk/shares` | | `logFiles` / `logFile` | `disk/log_files`，`disk/logs` | | `docker.containers` / `docker.networks` | `docker/*` | | `vms` | `vm/*` | | `notifications` | `notification/*` | | `apiKeys` / `apiKey` | `key/*` | | `plugins` | `plugin/list` | | `rclone` | `rclone/*` | | `connect` | `connect/status`（直接安全根；省略设置值），`connect/*` | | `customization` | `customization/details`（直接安全根；省略激活码值），`customization/*` | | `oidcProviders` / `oidcConfiguration` | `oidc/*` | | `me` | `user/me` | 订阅使用 WebSocket 上的 `graphql-transport-ws`（回退到旧版 `graphql-ws`）。WebSocket URL 通过交换方案（`http` → `ws`，`https` → `wss`）从 `UNRAID_API_URL` 派生。 ## 相关插件 | 插件 | 类别 | 描述 | |--------|----------|-------------| | [homelab-core](https://github.com/jmagar/claude-homelab) | 核心 | 核心代理、命令、技能和设置/健康工作流，用于家庭实验室管理。 | | [overseerr-mcp](https://github.com/jmagar/overseerr-mcp) | 媒体 | 通过 Overseerr 搜索电影和电视节目、提交请求和监视失败的请求。 | | [unifi-mcp](https://github.com/jmagar/unifi-mcp) | 基础设施 | 监视和管理 UniFi 设备、客户端、防火墙规则和网络健康状况。 | | [gotify-mcp](https://github.com/jmagar/gotify-mcp) | 实用工具 | 通过自托管的 Gotify 服务器发送和管理推送通知。 | | [swag-mcp](https://github.com/jmagar/swag-mcp) | 基础设施 | 创建、编辑和管理 SWAG nginx 反向代理配置。 | | [synapse-mcp](https://github.com/jmagar/synapse-mcp) | 基础设施 | 家庭实验室主机上的 Docker 管理（Flux）和 SSH 远程操作（Scout）。 | | [arcane-mcp](https://github.com/jmagar/arcane-mcp) | 基础设施 | 通过 Arcane 管理 Docker 环境、容器、镜像、卷、网络和 GitOps。 | | [syslog-mcp](https://github.com/jmagar/syslog-mcp) | 基础设施 | 通过 SQLite FTS5 接收、索引和搜索来自所有家庭实验室主机的 syslog 流。 | | [plugin-lab](https://github.com/jmagar/plugin-lab) | 开发工具 | 使用代理和规范模板搭建、审查、调整和部署家庭实验室 MCP 插件。 | ## 许可证 MIT