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

Subaction	Description
overview	Complete system summary (recommended starting point)
server	Hostname, version, uptime
servers	All known Unraid servers
array	Array status and disk list
network	Network interfaces and config
registration	License and registration status
variables	Environment variables
metrics	Real-time CPU, memory, I/O usage
services	Running services status
display	Display settings
config	System configuration
online	Quick online status check
owner	Server owner information
settings	User settings and preferences
flash	USB flash drive details
ups_devices	List all UPS devices
ups_device	Single UPS device (requires device_id)
ups_config	UPS configuration

health — Diagnostics

Subaction	Description
check	Comprehensive health check — connectivity, array, disks, containers, VMs, resources
test_connection	Test API connectivity and authentication
diagnose	Detailed diagnostic report with troubleshooting recommendations
setup	Report credential status + setup instructions (read-only; does not write or prompt)

array — Array & Parity

Subaction	Description
parity_status	Current parity check progress and status
parity_history	Historical parity check results
parity_start	Start a parity check (requires correct — True writes corrections, False checks only)
parity_pause	Pause a running parity check
parity_resume	Resume a paused parity check
parity_cancel	Cancel a running parity check
start_array	Start the array
stop_array	⚠️ Stop the array (requires confirm=True)
add_disk	Add a disk to the array (requires slot, id)
remove_disk	⚠️ Remove a disk (requires slot, confirm=True)
mount_disk	Mount a disk
unmount_disk	Unmount a disk
clear_disk_stats	⚠️ Clear disk statistics (requires confirm=True)

disk — Storage & Logs

Subaction	Description
shares	List network shares
disks	All physical disks with health and temperatures
disk_details	Detailed info for a specific disk (requires disk_id)
log_files	List available log files
logs	Read log content (requires log_path; optional tail_lines)
flash_backup	⚠️ Trigger a flash backup (requires confirm=True)

docker — Containers

Subaction	Description
list	All containers with status, image, state
details	Single container details (requires container identifier)
start	Start a container (requires container identifier)
stop	Stop a container (requires container identifier)
restart	Restart a container (requires container identifier)
networks	List Docker networks
network_details	Details for a specific network (requires network_id)

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

vm — Virtual Machines

Subaction	Description
list	All VMs with state
details	Single VM details (requires vm_id)
start	Start a VM (requires vm_id)
stop	Gracefully stop a VM (requires vm_id)
pause	Pause a VM (requires vm_id)
resume	Resume a paused VM (requires vm_id)
reboot	Reboot a VM (requires vm_id)
force_stop	⚠️ Force stop a VM (requires vm_id, confirm=True)
reset	⚠️ Hard reset a VM (requires vm_id, confirm=True)

notification — Notifications

Subaction	Description
overview	Notification counts (unread, archived by type)
list	List notifications (requires list_type: UNREAD/ARCHIVE; optional importance, limit, offset)
mark_unread	Mark a notification as unread (requires notification_id)
create	Create a notification (requires title, subject, description, importance)
archive	Archive a notification (requires notification_id)
delete	⚠️ Delete a notification (requires notification_id, notification_type, confirm=True)
delete_archived	⚠️ Delete all archived (requires confirm=True)
archive_all	Archive all unread notifications
archive_many	Archive multiple (requires ids list)
unarchive_many	Unarchive multiple (requires ids list)
unarchive_all	Unarchive all archived notifications
recalculate	Recalculate notification counts

key — API Keys

Subaction	Description
list	All API keys
get	Single key details (requires key_id)
create	Create a new key (requires name; optional roles, permissions)
update	Update a key (requires key_id)
delete	⚠️ Delete a key (requires key_id, confirm=True)
add_role	Add a role to a key (requires key_id, roles)
remove_role	Remove a role from a key (requires key_id, roles)

plugin — Plugins

Subaction	Description
list	All installed plugins
add	Install plugins (requires names — list of plugin names)
remove	⚠️ Uninstall plugins (requires names — list of plugin names, confirm=True)

rclone — Cloud Storage

Subaction	Description
list_remotes	List configured rclone remotes
config_form	Get configuration form for a remote type
create_remote	Create a new remote (requires name, provider_type, config_data)
delete_remote	⚠️ Delete a remote (requires name, confirm=True)

setting — System Settings

Subaction	Description
update	Update system settings (requires settings_input object)
configure_ups	⚠️ Configure UPS settings (requires confirm=True)

customization — Theme & Appearance

Subaction	Description
theme	Current theme settings
public_theme	Public-facing theme
is_initial_setup	Check if initial setup is complete
sso_enabled	Check SSO status
set_theme	Update theme (requires theme parameters)

oidc — SSO / OpenID Connect

Subaction	Description
providers	List configured OIDC providers
provider	Single provider details (requires provider_id)
configuration	OIDC configuration
public_providers	Public-facing provider list
validate_session	Validate current SSO session (requires token)

user — Current User

Subaction	Description
me	Current authenticated user info

live — Real-Time Subscriptions

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

Subaction	Description
cpu	Live CPU utilization
memory	Live memory usage
cpu_telemetry	Detailed CPU telemetry
array_state	Live array state changes
parity_progress	Live parity check progress
ups_status	Live UPS status
notifications_overview	Live notification counts
owner	Live owner info
server_status	Live server status
log_tail	Live log tail stream
notification_feed	Live notification feed

---

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.

Domain	Subaction	Risk
array	stop_array	Stops array while containers/VMs may use shares
array	remove_disk	Removes disk from array
array	clear_disk_stats	Clears disk statistics permanently
vm	force_stop	Hard kills VM without graceful shutdown
vm	reset	Hard resets VM
notification	delete	Permanently deletes a notification
notification	delete_archived	Permanently deletes all archived notifications
rclone	delete_remote	Removes a cloud storage remote
key	delete	Permanently deletes an API key
disk	flash_backup	Triggers flash backup operation
setting	configure_ups	Modifies UPS configuration
plugin	remove	Uninstalls a plugin

---

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="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: Docker container stdout/stderr are NOT accessible via API — use SSH + docker logs
• 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 }"