dinglebear-ai / unraid

Unraid MCP Skill

Mode Detection

MCP mode (preferred): Use when mcp__unraid-mcp__unraid tool is available.

HTTP fallback: Use when MCP tools are unavailable. Credentials live in the file
~/.unraid-mcp/.env; load it before running curl (see "HTTP Fallback Mode" below).
Do NOT use $CLAUDE_PLUGIN_OPTION_* in the Bash tool — Claude Code injects those vars
only into plugin subprocesses (hooks/MCP/LSP), not the Bash tool. The plugin's setup
hook reads them and materializes ~/.unraid-mcp/.env; the skill loads that file via
load-env.sh (which parses it, never executes it).

Use the single unraid MCP tool with action (domain) + subaction (operation) for all Unraid operations.

Setup

Credentials come from the plugin's configuration form (Unraid GraphQL API URL /
Unraid API Key) or a hand-edited ~/.unraid-mcp/.env. They are read once at server
startup, so after changing them you must restart the server / MCP client.

To check whether credentials are configured and the connection works:

unraid(action="health", subaction="setup")            # read-only status + instructions
unraid(action="health", subaction="test_connection")  # verify connectivity

setup does not prompt for or write credentials — it only reports the current status
and explains how to set them.

Calling Convention

unraid(action="<domain>", subaction="<operation>", [additional params])

Examples:

unraid(action="system",  subaction="overview")
unraid(action="docker",  subaction="list")
unraid(action="health",  subaction="check")
unraid(action="array",   subaction="parity_status")
unraid(action="disk",    subaction="disks")
unraid(action="vm",      subaction="list")
unraid(action="notification", subaction="overview")
unraid(action="live",    subaction="cpu")

All Domains and Subactions

system — Server Information

health — Diagnostics

array — Array & Parity

disk — Storage & Logs

docker — Containers

Container Identification: Name, ID, or partial name (fuzzy match supported).

vm — Virtual Machines

notification — Notifications

key — API Keys

plugin — Plugins

rclone — Cloud Storage

setting — System Settings

connect — Unraid Connect / Remote Access

All mutations change the server's cloud/remote-access posture and require confirm=True.

customization — Theme & Appearance

Secret-sensitive fields are omitted by default: server.apikey, connect.settings.values, and raw activation-code values are not returned by the safe read subactions (system/server_details, connect/status, customization/details).

oidc — SSO / OpenID Connect

onboarding — First-Boot / Setup State

Operate on the server's onboarding/setup state. Rarely needed on a configured
production server; the dangerous ones require confirm=True.

user — Current User

live — Real-Time Subscriptions

These use persistent WebSocket connections. Returns a "connecting" placeholder on the first call — retry momentarily for live data.

Destructive Actions

All require confirm=True as an explicit parameter. Without it, the action is blocked: interactive MCP clients are asked to confirm (elicitation), and non-interactive callers get a ToolError — re-run with confirm=True.

Common Workflows

Verify credentials

unraid(action="health", subaction="setup")            # status + instructions (read-only)
unraid(action="health", subaction="test_connection")  # confirm connectivity

System health overview

unraid(action="system", subaction="overview")
unraid(action="health", subaction="check")

Container management

unraid(action="docker", subaction="list")
unraid(action="docker", subaction="details", container_id="plex")
unraid(action="docker", subaction="logs", container_id="plex", tail_lines=100)
unraid(action="docker", subaction="check_updates")
unraid(action="docker", subaction="restart", container_id="sonarr")

Array and disk status

unraid(action="array",  subaction="parity_status")
unraid(action="disk",   subaction="disks")
unraid(action="system", subaction="array")

Read logs

unraid(action="disk", subaction="log_files")
unraid(action="disk", subaction="logs", log_path="/var/log/syslog", tail_lines=50)

Live monitoring

unraid(action="live", subaction="cpu")
unraid(action="live", subaction="memory")
unraid(action="live", subaction="array_state")

VM operations

unraid(action="vm", subaction="list")
unraid(action="vm", subaction="start",      vm_id="<id>")
unraid(action="vm", subaction="force_stop", vm_id="<id>", confirm=True)

Notes

• Rate limit: 100 requests / 10 seconds
• Log path validation: Only /var/log/, /boot/logs/, /mnt/ prefixes accepted
• Container logs: Use docker/logs with container_id and optional tail_lines
• arraySubscription: Known Unraid API bug — live/array_state may show "connecting" indefinitely
• Event-driven subs (notifications_overview, owner, server_status, ups_status): Only populate cache on first real server event

HTTP Fallback Mode

When MCP tools are unavailable, query the GraphQL API directly with curl. Load the
credentials first — $CLAUDE_PLUGIN_OPTION_* is not set in the Bash tool, so read
~/.unraid-mcp/.env (which the plugin's setup hook materializes) instead. Source the
bundled load-env.sh library and call its loader (it parses the .env, never executes it):

# Load UNRAID_API_URL / UNRAID_API_KEY from ~/.unraid-mcp/.env
source "$CLAUDE_PLUGIN_ROOT/skills/unraid/load-env.sh"
load_unraid_credentials || exit 1

# System overview
curl -s "$UNRAID_API_URL" \
  -H "x-api-key: $UNRAID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ info { os { hostname uptime } } }"}'

# List Docker containers
curl -s "$UNRAID_API_URL" \
  -H "x-api-key: $UNRAID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ docker { containers { names state status } } }"}'

# Array status
curl -s "$UNRAID_API_URL" \
  -H "x-api-key: $UNRAID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ array { state capacity { kilobytes { free used total } } disks { name status temp } } }"}'

Or use the helper script, which sources load-env.sh automatically:

"$CLAUDE_PLUGIN_ROOT/skills/unraid/scripts/unraid-query.sh" -q "{ online }"