Help us improve
Share bugs, ideas, or general feedback.
From unraid-management-agent-skills
Monitors and controls an Unraid server via MCP, REST, and WebSocket interfaces. Use for checking system status, managing containers/VMs/array, and diagnosing disk health.
npx claudepluginhub ruaan-deysel/unraid-management-agent --plugin unraid-management-agent-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/unraid-management-agent-skills:unraid-management-agentThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The **Unraid Management Agent** is a plugin that runs on an Unraid server and
Monitors and manages Unraid NAS servers: health checks, disk/array status, Docker containers, VMs, parity, logs, notifications, UPS, CPU/memory via API or MCP.
Unraid server management: array configuration, Docker containers, VMs, shares, plugins, user scripts, backup strategy, and security hardening. Invoke whenever task involves any interaction with Unraid — configuring storage, deploying containers, setting up VMs, managing shares, writing user scripts, planning backups, reviewing configurations, or troubleshooting Unraid systems.
Manages ZFS pools in homelabs: monitors health, configures Sanoid/Syncoid snapshots and replication, optimizes datasets, schedules scrubs, troubleshoots issues with double-confirmation for destructive ops.
Share bugs, ideas, or general feedback.
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 — 121 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.
If the client is not yet connected, read references/connection.md. In short:
http://<unraid-ip>:8043/mcp.unraid-management-agent mcp-stdio.Always establish current state with a read-only tool before taking action:
get_system_info, or get_diagnostic_summary for a broad viewget_array_status; Disks → list_disks / get_disk_infolist_containers / search_containers / get_container_infolist_vms / search_vms / get_vm_infoRead-only tools are marked ReadOnlyHint: true. The full catalog is in
references/mcp-tools.md.
search_containers / search_vms,
not a full list_ dump.get_ups_status,
get_gpu_metrics, get_zfs_pools, …) rather than scraping get_diagnostic_summary.query_metric_history, get_parity_history,
get_alert_history, get_health_check_history.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.
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.
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.
| 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 |
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 121 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) |