Unraid Management Agent
The Unraid Management Agent is a plugin that runs on an Unraid server and
exposes its full state and control surface over three interfaces:
| Interface |
Endpoint |
Use for |
| MCP (Model Context Protocol) |
http://<unraid-ip>:8043/mcp |
AI agents — 125 tools, 5 resources, 6 prompts |
| REST API |
http://<unraid-ip>:8043/api/v1 |
Scripts, Custom GPT Actions, integrations |
| WebSocket |
ws://<unraid-ip>:8043/api/v1/ws |
Live event streaming (near real-time) |
Core principle: prefer the MCP tools when acting as an AI agent — they
are purpose-built, validated, and named for discovery. Fall back to the REST API
only for clients that cannot speak MCP (e.g. ChatGPT Custom GPTs). Never invent
tool names or paths; the real catalogs are in the reference files below.
Decision Workflow
1. Connect
If the client is not yet connected, read references/connection.md. In short:
- Streamable HTTP (remote/LAN): point the client at
http://<unraid-ip>:8043/mcp.
- STDIO (local on the server): run
unraid-management-agent mcp-stdio.
- The agent has no authentication by default — it is designed for a trusted
LAN or behind a VPN/reverse proxy. Do not assume an API key exists unless the
user says so.
2. Read before you write
Always establish current state with a read-only tool before taking action:
- System snapshot →
get_system_info, or get_diagnostic_summary for a broad view
- Array →
get_array_status; Disks → list_disks / get_disk_info
- Containers →
list_containers / search_containers / get_container_info
- VMs →
list_vms / search_vms / get_vm_info
Read-only tools are marked ReadOnlyHint: true. The full catalog is in
references/mcp-tools.md.
3. Pick the narrowest tool
- Looking for one container/VM among many? Use
search_containers / search_vms,
not a full list_ dump.
- Want a specific subsystem? Use the dedicated getter (
get_ups_status,
get_gpu_metrics, get_zfs_pools, …) rather than scraping get_diagnostic_summary.
- Need history/metrics over time? Use
query_metric_history, get_parity_history,
get_alert_history, get_health_check_history.
4. Confirm destructive actions
Control tools (ReadOnlyHint: false) change the system. The high-risk ones
require confirm=true and must be confirmed with the user first:
| Tool |
Effect |
array_action (stop) |
Makes all array data inaccessible |
system_reboot / system_shutdown |
Restarts / powers off the whole server |
execute_user_script / run_runbook |
Runs arbitrary user-defined actions |
delete_vm_snapshot / restore_vm_snapshot |
Irreversible VM state change |
delete_alert_rule / delete_health_check |
Removes configuration |
Always state what will happen and wait for explicit user approval before sending
confirm=true. See references/mcp-tools.md for the full read/write breakdown.
5. Use live data correctly
For continuously changing values (CPU, container state), do not poll the REST
API in a tight loop. Use the MCP resources (references/diagnostics.md) or the
WebSocket stream. One MCP tool call returns the latest cached value already.
6. Diagnose with prompts, not ad-hoc chains
The agent ships 6 built-in diagnostic prompts that orchestrate the right
tools for common investigations (disk health, performance, maintenance, array
state, overview, troubleshooting). Prefer them over reinventing the analysis.
See references/diagnostics.md.
Critical Anti-Patterns
| Anti-pattern |
Use instead |
Why |
Inventing tool names (docker_restart, getArray) |
The exact names in references/mcp-tools.md |
Wrong names just fail |
| Stopping the array / rebooting without confirmation |
Read state, explain impact, then confirm=true |
Data loss / downtime |
Polling GET /api/v1/system in a loop |
MCP resources or WebSocket ws://…/api/v1/ws |
The agent already caches; polling wastes CPU |
list_containers then filtering in-context |
search_containers / get_container_info |
Less context, faster, more accurate |
| Hand-rolling a disk-health analysis |
diagnose_disk_health prompt |
Built-in prompt covers SMART, temps, wear, errors |
| Assuming an API key / auth header |
Treat as unauthenticated LAN/VPN unless told otherwise |
Default deploy has no auth |
| Using REST from an MCP-capable client |
The MCP tools |
Validated args, richer results, fewer round-trips |
| Editing Unraid config files directly |
The agent's control tools / settings endpoints |
Tools match the WebUI's own logic and validation |
Reference Files
Read these when you need detail. Keep SKILL.md itself in context; pull
references on demand.
| File |
When to read |
references/connection.md |
Connecting any client (Claude Code/Desktop, claude.ai, Cursor, Copilot, Gemini CLI, ChatGPT) via MCP HTTP/STDIO; troubleshooting connectivity |
references/mcp-tools.md |
The full catalog of all 125 MCP tools grouped by category, with read/write (destructive) flags and arguments |
references/diagnostics.md |
The 6 diagnostic prompts and 5 real-time resources — what each analyses and when to use it |
references/rest-api.md |
REST API surface for non-MCP clients (Custom GPT Actions, scripts): base path, key endpoints, path/body conventions |
references/workflows.md |
Natural-language request → tool/endpoint mappings and end-to-end examples (monitoring, container/VM/array control, maintenance) |
Capabilities at a Glance
- Monitoring (read-only): system, array, disks + SMART, shares, Docker
(containers, networks, stats, logs, update checks), VMs + snapshots, GPU, UPS,
NUT, ZFS (pools/datasets/snapshots/ARC), network + access URLs, hardware,
notifications, parity history, logs, collectors, settings, unassigned devices,
remote SMB/NFS shares.
- Control: container & VM lifecycle, array start/stop, parity check
start/stop/pause/resume, disk spin up/down, container & plugin updates, VM
snapshot create/delete/restore, VM clone, service start/stop/restart, user
scripts, collector enable/disable + intervals, reboot/shutdown.
- Observability & automation: alert rules (expr-lang) + templates, health
checks (HTTP/TCP/container), remediation runbooks, an optional autonomous
agent, fan control (profiles/curves), CPU governor, and system tuning (turbo
boost, disk cache, inotify).
1---2name: unraid-management-agent3description: >4 Monitor and control an Unraid server via the Unraid Management Agent's MCP5 server (125 tools, 5 resources, 6 diagnostic prompts) and REST API. Use when:6 connecting an AI client (Claude, ChatGPT, Cursor, Copilot, Gemini CLI) to7 Unraid; checking system, array, disk, Docker, VM, GPU, UPS, ZFS, or network8 status; starting/stopping containers, VMs, the array, or parity checks;9 diagnosing disk health, performance, or array state; managing alerts, health10 checks, fan/CPU/tuning, or updates; or choosing between MCP, REST, and11 WebSocket. Corrects: inventing Unraid tool names or REST paths; running12 destructive actions (stop array, reboot, delete snapshot) without confirm=true;13 polling REST in a loop instead of using WebSocket/MCP; dumping full lists14 instead of search_/get_ tools; and assuming auth the agent lacks by default.15metadata:16 source: https://skillmd.com/skills/ruaan-deysel/unraid-management-agent17 version: 118 homepage: https://github.com/ruaan-deysel/unraid-management-agent19---2021# Unraid Management Agent2223The **Unraid Management Agent** is a plugin that runs on an Unraid server and24exposes its full state and control surface over three interfaces:2526| Interface | Endpoint | Use for |27| --- | --- | --- |28| **MCP** (Model Context Protocol) | `http://<unraid-ip>:8043/mcp` | AI agents — 125 tools, 5 resources, 6 prompts |29| **REST API** | `http://<unraid-ip>:8043/api/v1` | Scripts, Custom GPT Actions, integrations |30| **WebSocket** | `ws://<unraid-ip>:8043/api/v1/ws` | Live event streaming (near real-time) |3132**Core principle:** prefer the **MCP tools** when acting as an AI agent — they33are purpose-built, validated, and named for discovery. Fall back to the REST API34only for clients that cannot speak MCP (e.g. ChatGPT Custom GPTs). Never invent35tool names or paths; the real catalogs are in the reference files below.3637## Decision Workflow3839### 1. Connect4041If the client is not yet connected, read `references/connection.md`. In short:4243- **Streamable HTTP (remote/LAN):** point the client at `http://<unraid-ip>:8043/mcp`.44- **STDIO (local on the server):** run `unraid-management-agent mcp-stdio`.45- The agent has **no authentication by default** — it is designed for a trusted46 LAN or behind a VPN/reverse proxy. Do not assume an API key exists unless the47 user says so.4849### 2. Read before you write5051Always establish current state with a read-only tool before taking action:5253- System snapshot → `get_system_info`, or `get_diagnostic_summary` for a broad view54- Array → `get_array_status`; Disks → `list_disks` / `get_disk_info`55- Containers → `list_containers` / `search_containers` / `get_container_info`56- VMs → `list_vms` / `search_vms` / `get_vm_info`5758Read-only tools are marked `ReadOnlyHint: true`. The full catalog is in59`references/mcp-tools.md`.6061### 3. Pick the narrowest tool6263- Looking for one container/VM among many? Use `search_containers` / `search_vms`,64 not a full `list_` dump.65- Want a specific subsystem? Use the dedicated getter (`get_ups_status`,66 `get_gpu_metrics`, `get_zfs_pools`, …) rather than scraping `get_diagnostic_summary`.67- Need history/metrics over time? Use `query_metric_history`, `get_parity_history`,68 `get_alert_history`, `get_health_check_history`.6970### 4. Confirm destructive actions7172Control tools (`ReadOnlyHint: false`) change the system. The high-risk ones73**require `confirm=true`** and must be confirmed with the user first:7475| Tool | Effect |76| --- | --- |77| `array_action` (stop) | Makes **all array data inaccessible** |78| `system_reboot` / `system_shutdown` | Restarts / powers off the whole server |79| `execute_user_script` / `run_runbook` | Runs arbitrary user-defined actions |80| `delete_vm_snapshot` / `restore_vm_snapshot` | Irreversible VM state change |81| `delete_alert_rule` / `delete_health_check` | Removes configuration |8283Always state what will happen and wait for explicit user approval before sending84`confirm=true`. See `references/mcp-tools.md` for the full read/write breakdown.8586### 5. Use live data correctly8788For continuously changing values (CPU, container state), do **not** poll the REST89API in a tight loop. Use the MCP resources (`references/diagnostics.md`) or the90WebSocket stream. One MCP tool call returns the latest cached value already.9192### 6. Diagnose with prompts, not ad-hoc chains9394The agent ships 6 built-in diagnostic **prompts** that orchestrate the right95tools for common investigations (disk health, performance, maintenance, array96state, overview, troubleshooting). Prefer them over reinventing the analysis.97See `references/diagnostics.md`.9899---100101## Critical Anti-Patterns102103| Anti-pattern | Use instead | Why |104| --- | --- | --- |105| Inventing tool names (`docker_restart`, `getArray`) | The exact names in `references/mcp-tools.md` | Wrong names just fail |106| Stopping the array / rebooting without confirmation | Read state, explain impact, then `confirm=true` | Data loss / downtime |107| Polling `GET /api/v1/system` in a loop | MCP resources or WebSocket `ws://…/api/v1/ws` | The agent already caches; polling wastes CPU |108| `list_containers` then filtering in-context | `search_containers` / `get_container_info` | Less context, faster, more accurate |109| Hand-rolling a disk-health analysis | `diagnose_disk_health` prompt | Built-in prompt covers SMART, temps, wear, errors |110| Assuming an API key / auth header | Treat as unauthenticated LAN/VPN unless told otherwise | Default deploy has no auth |111| Using REST from an MCP-capable client | The MCP tools | Validated args, richer results, fewer round-trips |112| Editing Unraid config files directly | The agent's control tools / settings endpoints | Tools match the WebUI's own logic and validation |113114---115116## Reference Files117118Read these when you need detail. Keep `SKILL.md` itself in context; pull119references on demand.120121| File | When to read |122| --- | --- |123| `references/connection.md` | Connecting any client (Claude Code/Desktop, claude.ai, Cursor, Copilot, Gemini CLI, ChatGPT) via MCP HTTP/STDIO; troubleshooting connectivity |124| `references/mcp-tools.md` | The full catalog of all 125 MCP tools grouped by category, with read/write (destructive) flags and arguments |125| `references/diagnostics.md` | The 6 diagnostic prompts and 5 real-time resources — what each analyses and when to use it |126| `references/rest-api.md` | REST API surface for non-MCP clients (Custom GPT Actions, scripts): base path, key endpoints, path/body conventions |127| `references/workflows.md` | Natural-language request → tool/endpoint mappings and end-to-end examples (monitoring, container/VM/array control, maintenance) |128129## Capabilities at a Glance130131- **Monitoring (read-only):** system, array, disks + SMART, shares, Docker132 (containers, networks, stats, logs, update checks), VMs + snapshots, GPU, UPS,133 NUT, ZFS (pools/datasets/snapshots/ARC), network + access URLs, hardware,134 notifications, parity history, logs, collectors, settings, unassigned devices,135 remote SMB/NFS shares.136- **Control:** container & VM lifecycle, array start/stop, parity check137 start/stop/pause/resume, disk spin up/down, container & plugin updates, VM138 snapshot create/delete/restore, VM clone, service start/stop/restart, user139 scripts, collector enable/disable + intervals, reboot/shutdown.140- **Observability & automation:** alert rules (expr-lang) + templates, health141 checks (HTTP/TCP/container), remediation runbooks, an optional autonomous142 agent, fan control (profiles/curves), CPU governor, and system tuning (turbo143 boost, disk cache, inotify).