unraid-mcp

MCP server for Unraid's official GraphQL API (Unraid 7.3.2 / unraid-api 4.35.1). Connects to /graphql on the standard web port — not port 31337.

Install

claude mcp add unraid -e UNRAID_HOST=tower.local -e UNRAID_API_KEY=your-key -- uvx unraid-mcp

Related MCP server: unraid-code-mode-mcp

Tool surface

One MCP tool: unraid(domain, action, **params).

Configuration

HTTP transport variables are read only when UNRAID_TRANSPORT=http. For every MCP_* variable (and FASTMCP_HOST/FASTMCP_PORT) surrounding whitespace is trimmed and "" means unset, so empty Unraid template fields are harmless.

The image sets no bind, so without MCP_HOST/MCP_PORT it binds 127.0.0.1 on port 8000.

HTTP authentication

With UNRAID_TRANSPORT=http the server fails closed: it refuses to start without a bearer-token file, and every request passes these checks in order before FastMCP routes it or reads its body:

Rejections carry a JSON-RPC body ({"jsonrpc":"2.0","error":{"code":-32000,"message":"Forbidden"|"Unauthorized"},"id":null}) and log one WARNING with the peer IP; the Authorization header is never logged. Unknown routes, POST /health, /health/ and //health all need the token. WebSocket connections are closed with code 1008.

Token file

Generate a 256-bit token:

(umask 077; openssl rand -base64 48 | tr '+/' '-_' | tr -d '=' > http-token)

MCP_AUTH_TOKEN_FILE (and UNRAID_API_KEY_FILE) must be:

• an absolute path to a regular file,

• mode 0600, owned by the effective uid of the server process (uid 10078 in the container image),

• non-empty UTF-8 text (surrounding whitespace is stripped).

The token must also be at least 43 characters from the RFC 6750 b64token charset (A-Z a-z 0-9 . _ ~ + / -, optional trailing =). Only its SHA-256 digest is kept in memory.

Startup refusals

The server exits with an unraid-mcp: http auth: … message when:

• no MCP_AUTH_TOKEN_FILE is set (and MCP_ALLOW_UNAUTHENTICATED is not 1);

• MCP_AUTH_TOKEN is set in the environment (even alongside a file);

• the token file fails any file check, is shorter than 43 characters or uses characters outside the b64token charset;

• MCP_ALLOW_UNAUTHENTICATED is anything other than 0/1, or is 1 on a non-loopback bind;

• the bind is 0.0.0.0 or :: and MCP_ALLOWED_HOSTS is unset;

• MCP_PORT/FASTMCP_PORT, or an entry of MCP_ALLOWED_CLIENTS, MCP_ALLOWED_HOSTS or MCP_ALLOWED_ORIGINS, is invalid.

At startup it logs a one-line summary (mode, bind, clients, hosts, origins) and a warning when, for example, MCP_ALLOWED_CLIENTS is unset on a non-loopback bind.

Example: container on monolith

The canonical dockerMan template is deploy/my-unraid-mcp.xml. The container uses host networking, binds only 10.10.10.50:8078 and reads the API at UNRAID_API_URL=http://127.0.0.1/graphql.

Why host networking: the old br0.500 macvlan container (a dedicated 10.10.10.x IP) could not reach its own host (macvlan host isolation), so every upstream read hung (#360). On the host network it reaches Unraid's nginx on 127.0.0.1:80.

UNRAID_TRANSPORT=http
UNRAID_API_URL=http://127.0.0.1/graphql
MCP_HOST=10.10.10.50
MCP_PORT=8078
MCP_ALLOWED_HOSTS=10.10.10.50
MCP_ALLOWED_CLIENTS=192.168.0.240
MCP_AUTH_TOKEN_FILE=/config/http-token     # image default
UNRAID_API_KEY_FILE=/config/unraid-api.key # image default; remove UNRAID_API_KEY

Run flags: --network host --user 10078:10078 --read-only --cap-drop ALL --security-opt no-new-privileges, with /config mounted read-only. The appdata directory is owned by 10078:10078 with mode 700; http-token and unraid-api.key are owned by 10078:10078 with mode 600.

Deploy from this repo (dry run first, then for real; MONOLITH overrides the default root@192.168.0.50):

deploy/deploy.sh --backup-suffix YYYYMMDD-tag --dry-run
deploy/deploy.sh --backup-suffix YYYYMMDD-tag

It builds the image, backs up the live template and autostart file, records the owners/modes of the appdata directory and both secrets (/var/lib/docker/unraid-autostart.bak-<suffix>.owners) and tags the running image unraid-mcp:bak-<suffix>, then ships the new image, installs the template, fixes secret ownership/modes, keeps unraid-mcp in autostart, rebuilds the container and verifies the listener is exactly 10.10.10.50:8078 and the container runs the image ID it built. If any step from the backup on fails it prints the backups and the restore commands (template, autostart, secret owners/modes back to the recorded ones — the previous image ran as root — docker tag back, rebuild).

Check it from an allowed client:

curl -s http://10.10.10.50:8078/health          # 200 {"status":"ok"}
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://10.10.10.50:8078/mcp  # 401

Live HTTP smoke (token from UNRAID_MCP_TOKEN_FILE, default ~/.config/unraid-mcp/http-token):

UNRAID_MCP_LIVE_URL=http://10.10.10.50:8078 uv run pytest tests/test_live_http.py --no-cov

FastMCP native auth vs this guard

FastMCP 4's own options were evaluated and are not used:

• HostOriginGuardMiddleware answers a bad Host with a plain-text 421, always merges its default hosts and the bound address, accepts wildcards and a same-origin fallback, and skips Host checks on non-loopback binds in "auto" mode. It is pinned off with host_origin_protection=False.

• Native auth (RequireAuthMiddleware with StaticTokenVerifier or DebugTokenVerifier) wraps only the /mcp route, leaving custom and unknown routes open; its challenge is RFC 9728 resource_metadata rather than a realm; StaticTokenVerifier keeps plaintext tokens with a non-constant-time lookup; DebugTokenVerifier accepts any token; nothing filters by source IP.

What is used from FastMCP: custom_route (for /health), middleware= (to put the pure-ASGI AuthGuard in front of routing) and uvicorn_config= (to force proxy_headers=False, so X-Forwarded-For never replaces the socket peer).

Safety

Two independent write locks prevent accidental mutations:

1. Server-level: writes are refused unless UNRAID_ALLOW_WRITES=1. Default is read-only. Refusal is a structured write_disabled error whose hint names the env var.

2. Call-level: every write action requires confirm=true or an MCP elicitation prompt (choices yes / no) that the user accepts and answers yes. The match is exact and case-sensitive: accepting with no, an empty or missing answer, or any other value (YES, yes) refuses the write, as do a declined or cancelled prompt. FastMCP 4 offers elicitation only on initialize-handshake (legacy) connections; on a 2026-07-28 connection the prompt cannot be sent, so the write is refused unless confirm=true is passed.

For defence in depth, use a VIEWER-role API key so the Unraid API itself rejects mutations regardless of server configuration.

docker restart is implemented as stop then start (the API has no restart mutation).

Non-goals (v1)

Not implemented: disk add/remove, clearArrayDiskStatistics, removeContainer, VM forceStop/reset, API-key mutations, OIDC, rclone, updateSettings, flash backup, plugin install/remove, GraphQL subscriptions.

Each returns a structured not_implemented error naming the reason.

Errors

A failed call returns an MCP tool error (isError: true) whose text is compact JSON:

{"code":"write_disabled","message":"Write operations are disabled.","hint":"Set UNRAID_ALLOW_WRITES=1 to enable."}

code is always present (write_disabled, confirmation_required, unknown_action, not_implemented, invalid_params, unauthorized, not_found, introspection_disabled, upstream_error, connection_failed); hint and details appear when set. Redaction before the error leaves the server:

• GraphQL extensions allowlist: of an upstream GraphQL error's extensions, only code (when a string) is forwarded, as details.extensions.code; every other extension key is dropped.

• By key name (details, any depth): a dict value is replaced by ***REDACTED*** when any segment of its key — split on non-alphanumerics and camelCase, singular or plural — is key, apikey, token, secret, password, passwd, pwd, authorization, auth, cookie, session, credential or bearer, or when the key, lowercased with non-alphanumerics removed, contains one of the unambiguous words password, passwd, secret, apikey, accesskey, privatekey, sshkey, token, credential, authorization, cookie, bearer, session. So apiKey, x-api-key, dbpassword, clientsecret, sshkeys match; keyword, monkeyCount, author do not. Subtrees deeper than 20 levels are replaced wholesale.

• By value (the whole error text — message, hint, details): the configured API key (when at least 8 characters long) and Bearer <token> strings are masked. The same scrubbing applies to the server's unraid <domain>.<action> failed: <code>: <message> warning log line, where control characters (newlines) are also escaped.

Not detected: other secrets inside free text, or under key names that match neither rule (for example a database password embedded in a dsn URL). These guarantees cover structured (UnraidError) failures only. Unexpected (non-Unraid) exceptions keep FastMCP's generic Error calling tool 'unraid': … text and are logged with a full traceback; neither is scrubbed.

Development

uv sync
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest

Live tests against a real Unraid server (read-only):

UNRAID_LIVE=1 uv run --env-file .env pytest tests/test_live.py --no-cov

Live HTTP smoke against a deployed server (token from UNRAID_MCP_TOKEN_FILE, default ~/.config/unraid-mcp/http-token):

UNRAID_MCP_LIVE_URL=http://10.10.10.50:8078 uv run pytest tests/test_live_http.py --no-cov

License

MIT