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).
Source: ruaan-deysel/unraid-management-agent — distributed by TomeVault.
1---2name: ruaan-deysel-unraid-management-agent-unraid-management-agent3description: Unraid Management Agent4---56# Unraid Management Agent78The **Unraid Management Agent** is a plugin that runs on an Unraid server and9exposes its full state and control surface over three interfaces:1011| Interface | Endpoint | Use for |12| --- | --- | --- |13| **MCP** (Model Context Protocol) | `http://<unraid-ip>:8043/mcp` | AI agents — 125 tools, 5 resources, 6 prompts |14| **REST API** | `http://<unraid-ip>:8043/api/v1` | Scripts, Custom GPT Actions, integrations |15| **WebSocket** | `ws://<unraid-ip>:8043/api/v1/ws` | Live event streaming (near real-time) |1617**Core principle:** prefer the **MCP tools** when acting as an AI agent — they18are purpose-built, validated, and named for discovery. Fall back to the REST API19only for clients that cannot speak MCP (e.g. ChatGPT Custom GPTs). Never invent20tool names or paths; the real catalogs are in the reference files below.2122## Decision Workflow2324### 1. Connect2526If the client is not yet connected, read `references/connection.md`. In short:2728- **Streamable HTTP (remote/LAN):** point the client at `http://<unraid-ip>:8043/mcp`.29- **STDIO (local on the server):** run `unraid-management-agent mcp-stdio`.30- The agent has **no authentication by default** — it is designed for a trusted31 LAN or behind a VPN/reverse proxy. Do not assume an API key exists unless the32 user says so.3334### 2. Read before you write3536Always establish current state with a read-only tool before taking action:3738- System snapshot → `get_system_info`, or `get_diagnostic_summary` for a broad view39- Array → `get_array_status`; Disks → `list_disks` / `get_disk_info`40- Containers → `list_containers` / `search_containers` / `get_container_info`41- VMs → `list_vms` / `search_vms` / `get_vm_info`4243Read-only tools are marked `ReadOnlyHint: true`. The full catalog is in44`references/mcp-tools.md`.4546### 3. Pick the narrowest tool4748- Looking for one container/VM among many? Use `search_containers` / `search_vms`,49 not a full `list_` dump.50- Want a specific subsystem? Use the dedicated getter (`get_ups_status`,51 `get_gpu_metrics`, `get_zfs_pools`, …) rather than scraping `get_diagnostic_summary`.52- Need history/metrics over time? Use `query_metric_history`, `get_parity_history`,53 `get_alert_history`, `get_health_check_history`.5455### 4. Confirm destructive actions5657Control tools (`ReadOnlyHint: false`) change the system. The high-risk ones58**require `confirm=true`** and must be confirmed with the user first:5960| Tool | Effect |61| --- | --- |62| `array_action` (stop) | Makes **all array data inaccessible** |63| `system_reboot` / `system_shutdown` | Restarts / powers off the whole server |64| `execute_user_script` / `run_runbook` | Runs arbitrary user-defined actions |65| `delete_vm_snapshot` / `restore_vm_snapshot` | Irreversible VM state change |66| `delete_alert_rule` / `delete_health_check` | Removes configuration |6768Always state what will happen and wait for explicit user approval before sending69`confirm=true`. See `references/mcp-tools.md` for the full read/write breakdown.7071### 5. Use live data correctly7273For continuously changing values (CPU, container state), do **not** poll the REST74API in a tight loop. Use the MCP resources (`references/diagnostics.md`) or the75WebSocket stream. One MCP tool call returns the latest cached value already.7677### 6. Diagnose with prompts, not ad-hoc chains7879The agent ships 6 built-in diagnostic **prompts** that orchestrate the right80tools for common investigations (disk health, performance, maintenance, array81state, overview, troubleshooting). Prefer them over reinventing the analysis.82See `references/diagnostics.md`.8384---8586## Critical Anti-Patterns8788| Anti-pattern | Use instead | Why |89| --- | --- | --- |90| Inventing tool names (`docker_restart`, `getArray`) | The exact names in `references/mcp-tools.md` | Wrong names just fail |91| Stopping the array / rebooting without confirmation | Read state, explain impact, then `confirm=true` | Data loss / downtime |92| Polling `GET /api/v1/system` in a loop | MCP resources or WebSocket `ws://…/api/v1/ws` | The agent already caches; polling wastes CPU |93| `list_containers` then filtering in-context | `search_containers` / `get_container_info` | Less context, faster, more accurate |94| Hand-rolling a disk-health analysis | `diagnose_disk_health` prompt | Built-in prompt covers SMART, temps, wear, errors |95| Assuming an API key / auth header | Treat as unauthenticated LAN/VPN unless told otherwise | Default deploy has no auth |96| Using REST from an MCP-capable client | The MCP tools | Validated args, richer results, fewer round-trips |97| Editing Unraid config files directly | The agent's control tools / settings endpoints | Tools match the WebUI's own logic and validation |9899---100101## Reference Files102103Read these when you need detail. Keep `SKILL.md` itself in context; pull104references on demand.105106| File | When to read |107| --- | --- |108| `references/connection.md` | Connecting any client (Claude Code/Desktop, claude.ai, Cursor, Copilot, Gemini CLI, ChatGPT) via MCP HTTP/STDIO; troubleshooting connectivity |109| `references/mcp-tools.md` | The full catalog of all 125 MCP tools grouped by category, with read/write (destructive) flags and arguments |110| `references/diagnostics.md` | The 6 diagnostic prompts and 5 real-time resources — what each analyses and when to use it |111| `references/rest-api.md` | REST API surface for non-MCP clients (Custom GPT Actions, scripts): base path, key endpoints, path/body conventions |112| `references/workflows.md` | Natural-language request → tool/endpoint mappings and end-to-end examples (monitoring, container/VM/array control, maintenance) |113114## Capabilities at a Glance115116- **Monitoring (read-only):** system, array, disks + SMART, shares, Docker117 (containers, networks, stats, logs, update checks), VMs + snapshots, GPU, UPS,118 NUT, ZFS (pools/datasets/snapshots/ARC), network + access URLs, hardware,119 notifications, parity history, logs, collectors, settings, unassigned devices,120 remote SMB/NFS shares.121- **Control:** container & VM lifecycle, array start/stop, parity check122 start/stop/pause/resume, disk spin up/down, container & plugin updates, VM123 snapshot create/delete/restore, VM clone, service start/stop/restart, user124 scripts, collector enable/disable + intervals, reboot/shutdown.125- **Observability & automation:** alert rules (expr-lang) + templates, health126 checks (HTTP/TCP/container), remediation runbooks, an optional autonomous127 agent, fan control (profiles/curves), CPU governor, and system tuning (turbo128 boost, disk cache, inotify).129130---131> Source: [ruaan-deysel/unraid-management-agent](https://github.com/ruaan-deysel/unraid-management-agent) — distributed by [TomeVault](https://tomevault.io).132<!-- tomevault:4.0:skill_md:2026-07-05 -->
tomevault-io