unraid

unraid-mcp

Rust MCP server that bridges Claude (and any MCP client) to the Unraid server GraphQL API. Exposes 24 read-only data actions covering array health, Docker, VMs, shares, logs, metrics, UPS, and more, plus a status observability action and a help action.

Architecture

                      ┌────────────────────────────────────┐
  Claude / MCP ◀────▶ │  POST /mcp  (RMCP Streamable HTTP) │
  stdio client ◀────▶ │  runraid mcp  (stdio transport)     │
                      │                                    │
                      │  mcp/tools.rs  ─▶  app.rs          │
                      │                       │            │
                      │                  graphql.rs        │
                      │                       │            │
                      │             POST <UNRAID_API_URL>   │
                      │             x-api-key: <key>       │
                      └───────────────────────┼────────────┘
                                              │
                              Unraid GraphQL API (myunraid.net)

• graphql.rs — HTTP client: POSTs GraphQL queries to the Unraid API with the x-api-key header
• app.rs — UnraidService: business layer, one method per action, no logic
• mcp/tools.rs — thin shim: parse JSON args, call service, return Value
• cli.rs — thin shim: parse CLI args, call service, format and print
• main.rs — mode dispatch: HTTP MCP server, stdio MCP, or CLI

Quickstart

Prerequisites

• Rust 1.90+ (rustup show)
• Unraid API URL and API key (Settings → API Management in Unraid)

Run

git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp

# Set required environment variables
export UNRAID_API_URL="https://10-1-0-2.<hash>.myunraid.net:31337/graphql"
export UNRAID_API_KEY="your-api-key-here"
export UNRAID_MCP_PORT=40010
export UNRAID_MCP_DISABLE_HTTP_AUTH=true

# Or copy .env and edit it
cp .env .env.local

# Start the MCP HTTP server
cargo run -- serve mcp

# Verify it is up
curl -sf http://localhost:40010/health | jq .
# → {"status":"ok"}

First MCP call

curl -s -X POST http://localhost:40010/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "unraid",
      "arguments": {"action": "server"}
    }
  }' | jq .result.content[0].text | jq -r . | jq .

Transports

Mode	Command	Description
HTTP MCP	runraid serve mcp or runraid (no args)	RMCP Streamable HTTP on POST /mcp
stdio MCP	runraid mcp	For MCP clients that launch the server as a child process
CLI	runraid <command>	Human-readable or --json output

MCP Tool Reference

One tool is exposed: unraid. Set the required action argument to select the operation.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "unraid",
    "arguments": {"action": "array"}
  }
}

Core actions

Action	Description
array	Array state, disk health, parity check status, capacity
disks	Physical disks with SMART status, temperature, interface type
docker	All Docker containers: state, status, ports, update availability
docker_logs	Container logs — requires id, optional tail (default 100)
vms	Virtual machines and their state
server	Server identity, LAN/WAN IP, local and remote URLs
info	OS, CPU, memory layout, Unraid and kernel versions
shares	User shares with size, cache settings, LUKS status
notifications	Active warnings and alerts with overview counts

System actions

Action	Description
services	Running system services with uptime
network	Network access URLs (type, name, IPv4, IPv6)
metrics	Live CPU percent per core, memory usage, temperature sensors
vars	System configuration variables (hostname, sharing, SSL, SSH)
registration	License type, state, expiry
flash	USB flash drive vendor and product info

Log actions

Action	Description	Extra args
log_files	List available log files with sizes and modification times	—
log_file	Read a log file	path (required), lines, start_line

Storage actions

Action	Description
parity_history	All past parity check results (date, duration, speed, errors)
rclone	Backup remote configurations and drive names

UPS actions

Action	Description
ups	UPS devices: battery charge, estimated runtime, power load
ups_config	UPS monitoring configuration (service, type, shutdown thresholds)

Remote access actions