Unraid RMCP

Official

by jmagar · Rust

Rust MCP server and CLI for Unraid GraphQL, NAS, Docker, VM, and storage workflows.

Topics

automationclaude-codeclaude-code-pluginsclicodexdockergeminigraphqlhomelabmcpmcp-servermodel-context-protocolnasoauthrmcpruststorageunraidvirtualization

README.md18 KBView on GitHub

unraid-rmcp

unraid-rmcp is a Rust MCP server and CLI for querying an Unraid NAS through the Unraid GraphQL API.

It exposes one MCP tool, unraid, plus the runraid CLI. Agents can inspect array health, disks, Docker containers and logs, VMs, shares, notifications, system metrics, UPS, logs, network settings, plugins, parity history, rclone, remote access, and Unraid Connect through stdio MCP, Streamable HTTP MCP, or direct shell commands.

30-second path: set UNRAID_API_URL and UNRAID_API_KEY, then run npx -y unraid-rmcp server --json -> start loopback HTTP with UNRAID_RMCP_HOST=127.0.0.1 npx -y unraid-rmcp serve mcp -> call tools/call with {"action":"server"}.

Status: operational RMCP upstream-client server. Read-only action surface; no Unraid mutations are exposed. HTTP MCP supports loopback dev mode, static bearer tokens, and Google OAuth through lab-auth. Release binaries and Docker images target linux/amd64 only.

Not for: replacing the Unraid web UI, mutating array/docker/VM state, running arbitrary shell commands, storing API keys for callers, multi-tenant isolation, or passing Unraid API keys through MCP tool arguments.

Naming
Capabilities And Boundaries
Install
Quickstart
Client Configuration
Runtime Surfaces
MCP Tool Reference
CLI Reference
Configuration
Authentication
Safety And Trust Model
Architecture
Distribution Contract
Development
Verification
Deployment
Troubleshooting
Related Servers
Documentation
License

Naming

Surface	This repo
Repository	`unraid-rmcp`
Rust crate	`unraid-rmcp`
Binary / CLI	`runraid`
npm package	`unraid-rmcp`
npm binary aliases	`unraid-rmcp`, `runraid`
MCP tool	`unraid`
Config home	`~/.unraid` on hosts, `/data` in containers
Env prefixes	`UNRAID_`, `UNRAID_RMCP_`

This repo is a small naming exception in the RMCP family: MCP/server variables use UNRAID_RMCP_* rather than UNRAID_MCP_* for compatibility with the existing deployment config.

Capabilities And Boundaries

Read Unraid array state, parity status, disk health, SMART summaries, and capacity.
Read Docker containers, container logs, VMs, shares, notifications, services, network URLs, live metrics, config vars, registration, flash device details, UPS, plugins, parity history, rclone, remote access, and Unraid Connect.
Provide pagination/filtering for MCP list actions and output truncation for large MCP responses.
Expose the server_summary prompt and unraid://schema/mcp-tool schema resource.
Provide setup and doctor commands for local plugin/runtime checks.

This repo owns	Unraid owns	Explicitly out of scope
MCP/CLI projection, GraphQL query selection, response shaping, pagination, auth policy, setup checks, prompt/resource metadata, and read-only safety.	NAS state, array/docker/VM behavior, GraphQL schema, Unraid API key issuance, remote access, and Connect state.	Mutations, shell execution, controller UI replacement, credential brokerage, background monitoring, multi-tenant sandboxing, and direct filesystem writes.

Install

Path	Command	Best for	Notes
npm / npx	`npx -y unraid-rmcp --help`	Local MCP clients and quick trials.	Downloads the matching `runraid` binary from GitHub Releases.
Release installer	`curl -fsSL https://raw.githubusercontent.com/jmagar/unraid-rmcp/main/scripts/install.sh \| bash`	Host installs without Node.	Installs `runraid` for linux/amd64.
Docker / Compose	`docker compose up -d`	Shared HTTP MCP deployments.	Reads `.env` and exposes container port `40010`.
Build from source	`cargo build --release`	Development and audits.	Produces `target/release/runraid`.
Plugin	`claude plugin install plugins/unraid`	Claude Code local plugin setup from this checkout.	Uses the packaged setup hook, skill, and local runtime metadata.

npm / npx

Run the stdio MCP server or CLI without a manual binary install:

bash

npx -y unraid-rmcp --help
npx -y unraid-rmcp mcp
npx -y unraid-rmcp server --json

The npm package downloads runraid during postinstall. Override download behavior only when testing packaging:

Variable	Purpose
`UNRAID_RMCP_SKIP_DOWNLOAD=1`	Skip postinstall binary download.
`UNRAID_RMCP_VERSION` or `UNRAID_RMCP_BINARY_VERSION`	Select the GitHub Release tag.
`UNRAID_RMCP_REPO`	Select the GitHub repo used for release downloads.
`UNRAID_RMCP_RELEASE_BASE_URL`	Select a custom release base URL.

Build From Source

bash

git clone https://github.com/jmagar/unraid-rmcp
cd unraid-rmcp
cargo build --release
./target/release/runraid --help

Minimum supported Rust version: 1.90.

Quickstart

1. Configure Unraid

Create an Unraid API key in Settings -> API Management, then set:

bash

export UNRAID_API_URL="https://10-1-0-2.<hash>.myunraid.net:31337/graphql"
export UNRAID_API_KEY="your-api-key-here"

Set UNRAID_API_SKIP_TLS_VERIFY=true only when your Unraid GraphQL endpoint uses a certificate your host does not trust.

2. Run A Safe CLI Call

bash

npx -y unraid-rmcp server --json

3. Start Loopback HTTP MCP

bash

UNRAID_RMCP_HOST=127.0.0.1 npx -y unraid-rmcp serve mcp

In another shell:

bash

curl -sf http://127.0.0.1:40010/health

4. Make A First MCP Call

bash

curl -s -X POST http://127.0.0.1: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"}}}'

Client Configuration

Claude Code Stdio

json

{
  "mcpServers": {
    "unraid": {
      "command": "npx",
      "args": ["-y", "unraid-rmcp", "mcp"],
      "env": {
        "UNRAID_API_URL": "https://10-1-0-2.<hash>.myunraid.net:31337/graphql",
        "UNRAID_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code HTTP

json

{
  "mcpServers": {
    "unraid": {
      "type": "http",
      "url": "http://127.0.0.1:40010/mcp",
      "headers": {
        "Authorization": "Bearer ${UNRAID_RMCP_TOKEN}"
      }
    }
  }
}

Codex / Labby Gateway

Register Unraid through Labby as an HTTP upstream when sharing one long-running server, or run it directly as stdio for local-only use.

toml

[mcp_servers.unraid]
command = "npx"
args = ["-y", "unraid-rmcp", "mcp"]

Generic MCP JSON

json

{
  "command": "runraid",
  "args": ["mcp"],
  "env": {
    "UNRAID_API_URL": "https://10-1-0-2.<hash>.myunraid.net:31337/graphql",
    "UNRAID_API_KEY": "your-api-key-here"
  }
}

Do not put UNRAID_API_KEY, OAuth secrets, passwords, SSH keys, or upstream bearer tokens in MCP tool arguments. Use env, config files, or the MCP client's secret storage. MCP callers never provide credentials, tokens, keys, or secrets as action arguments.

Runtime Surfaces

Surface	Status	Entry point	Purpose
MCP stdio	Supported	`runraid mcp`, `npx -y unraid-rmcp mcp`	Local child-process MCP clients.
MCP HTTP	Supported	`runraid serve mcp`, `POST /mcp`	Streamable HTTP MCP for local or shared server deployments.
CLI	Supported	`runraid <command>`	Scriptable parity and debugging.
Prompt	Supported	`server_summary`	Guides a model to call `info` and summarize server state.
Resource	Supported	`unraid://schema/mcp-tool`	JSON schema for the `unraid` tool.
Health endpoint	Supported	`GET /health`	Unauthenticated liveness check.
REST API	Not shipped	N/A	Unraid owns the GraphQL API.
Web UI	Not shipped	N/A	Unraid owns the web UI.

MCP Tool Reference

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

Core Actions

Action	Description	Required params	Optional params
`array`	Array state, disk health, parity check status, and capacity.	none	none
`disks`	Physical disks with SMART status, temperature, size, interface, and partitions.	none	`limit`, `offset`, `name`
`docker`	Docker containers with state, status, ports, and update availability.	none	`limit`, `offset`, `state`, `name`
`docker_logs`	Container log lines.	`id`	`tail`
`vms`	Virtual machines and state.	none	`limit`, `offset`, `state`, `name`
`server`	Server identity, LAN/WAN IP, local/remote URLs, GUID, and online status.	none	none
`info`	OS, CPU, memory layout, Unraid version, and kernel version.	none	none
`shares`	User shares with size, cache settings, and encryption state.	none	`limit`, `offset`, `name`
`notifications`	Active warnings and alerts with overview counts.	none	none

System Actions

Action	Description
`services`	Running system services with uptime.
`network`	Network access URLs and addresses.
`metrics`	Live CPU, memory, and temperature sensor data.
`vars`	System configuration variables.
`registration`	License type, state, and expiry.
`flash`	USB flash drive details.

Log And Storage Actions

Action	Description	Required params	Optional params
`log_files`	Available log files with sizes and modified times.	none	none
`log_file`	Read a log file.	`path`	`lines`, `start_line`
`parity_history`	Past parity check results.	none	none
`rclone`	Backup remote configurations and drive names.	none	none

UPS, Remote, Plugin, And Meta Actions

Action	Description
`ups`	UPS devices, charge, runtime, and load.
`ups_config`	UPS monitoring configuration.
`remote_access`	WAN access and port forwarding configuration.
`connect`	Unraid Connect dynamic remote access state.
`plugins`	Installed community plugins with versions.
`status`	Server observability: version, PID, uptime, and counters.
`help`	Markdown reference for all actions.

Pagination and filtering are MCP-only. List actions return a paginated envelope with items, total, limit, offset, has_more, and next_offset.

CLI Reference

All CLI commands accept --json for machine-readable output.

bash

runraid array [--json]
runraid disks [--json]
runraid docker [--json]
runraid docker logs <id> [--tail N] [--json]
runraid vms [--json]
runraid server [--json]
runraid info [--json]
runraid shares [--json]
runraid notifications [--json]
runraid services [--json]
runraid network [--json]
runraid metrics [--json]
runraid vars [--json]
runraid registration [--json]
runraid flash [--json]
runraid log-files [--json]
runraid log <path> [--lines N] [--start-line N] [--json]
runraid parity-history [--json]
runraid rclone [--json]
runraid ups [--json]
runraid ups-config [--json]
runraid remote-access [--json]
runraid connect [--json]
runraid plugins [--json]
runraid doctor [--json]
runraid setup check [--json]
runraid setup repair [--json]

status is MCP-only; setup and doctor are CLI-only.

Configuration

Host installs read ~/.unraid/.env before loading config. Containers read /data/.env. Process environment overrides both.

Variable	Default	Purpose
`UNRAID_API_URL`	unset	Full Unraid GraphQL endpoint URL.
`UNRAID_API_KEY`	unset	API key for the `x-api-key` header.
`UNRAID_API_SKIP_TLS_VERIFY`	`false`	Skip TLS certificate verification for self-signed endpoints.
`UNRAID_RMCP_HOST`	`0.0.0.0`	HTTP bind host.
`UNRAID_RMCP_PORT`	`40010`	HTTP bind port.
`UNRAID_RMCP_SERVER_NAME`	`unraid-rmcp`	Advertised MCP server name.
`UNRAID_RMCP_TOKEN`	unset	Static bearer token for HTTP MCP.
`UNRAID_RMCP_NO_AUTH`	`false`	Disable auth only for loopback development.
`UNRAID_RMCP_DISABLE_HTTP_AUTH`	`false`	Compatibility alias for disabling auth.
`UNRAID_NOAUTH`	`false`	Trust an upstream gateway to enforce auth.
`UNRAID_RMCP_ALLOWED_HOSTS`	unset	Extra accepted Host header values.
`UNRAID_RMCP_ALLOWED_ORIGINS`	unset	Extra accepted CORS origins.
`UNRAID_RMCP_PUBLIC_URL`	unset	Public URL for OAuth metadata.
`UNRAID_RMCP_AUTH_MODE`	`bearer`	`bearer` or `oauth`.
`UNRAID_RMCP_GOOGLE_CLIENT_ID`	unset	Google OAuth client ID.
`UNRAID_RMCP_GOOGLE_CLIENT_SECRET`	unset	Google OAuth client secret.
`UNRAID_RMCP_AUTH_ADMIN_EMAIL`	unset	Admin email for OAuth bootstrap.

Authentication

Stdio MCP runs as a local trusted child process and does not use HTTP auth.

HTTP MCP auth policy:

State	Condition	Behavior
Loopback dev	`UNRAID_RMCP_HOST` starts with `127.` or auth is explicitly disabled on loopback	Local unauthenticated development is allowed.
Mounted bearer	Non-loopback with `UNRAID_RMCP_TOKEN`	Requires `Authorization: Bearer <token>` and action scopes.
Mounted OAuth	`UNRAID_RMCP_AUTH_MODE=oauth`	Uses Google OAuth/JWT through `lab-auth`.
Trusted gateway	`UNRAID_NOAUTH=true`	Assumes a reverse proxy or gateway already enforced auth.

All data actions are read-only. OAuth exposes unraid:read and unraid:admin scopes, but no mutating Unraid action is currently registered.

Safety And Trust Model

Unraid API keys are loaded from config/env only.
MCP callers select read actions and filters, not upstream credentials.
No mutation, shell execution, filesystem write, Docker control, VM control, or array-control action is exposed.
log_file reads through the Unraid GraphQL API, not arbitrary local files.
Non-loopback HTTP deployments must use bearer auth, OAuth, or a trusted authenticated gateway.
This bridge does not sandbox Unraid itself. Unraid remains responsible for API permissions and GraphQL response semantics.

Architecture

text

GraphQL queries (src/graphql.rs)  typed/read-only query construction
        |
UnraidService (src/app.rs)       action behavior and response shaping
        |
MCP shim      (src/mcp/tools.rs) JSON args -> service -> Value
CLI shim      (src/cli.rs)       argv -> service -> stdout

Distribution Contract

Cargo.toml, Cargo.lock, packages/unraid-rmcp/package.json, .release-please-manifest.json, and server.json must agree on the released version.
GitHub Releases publish the linux/amd64 runraid binary consumed by the npm launcher.
The npm package name is unraid-rmcp; binary aliases are unraid-rmcp and runraid.
Docker/OCI metadata uses ghcr.io/jmagar/unraid-rmcp:<version>.
plugins/unraid/.mcp.json must launch npx -y unraid-rmcp mcp so stdio clients start the MCP transport rather than the HTTP server.
The root README is curated. docs/INVENTORY.md is the curated inventory for actions, CLI commands, env vars, HTTP endpoints, and dependencies.

Development

bash

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
npm --prefix packages/unraid-rmcp run check

Verification

bash

python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md
npm --prefix packages/unraid-rmcp run check
cargo check
cargo test
git diff --check

Runtime smoke:

bash

UNRAID_API_URL=https://10-1-0-2.<hash>.myunraid.net:31337/graphql \
UNRAID_API_KEY=... \
runraid server --json

HTTP smoke:

bash

UNRAID_RMCP_HOST=127.0.0.1 runraid serve mcp
curl -sf http://127.0.0.1:40010/health

Deployment

Use loopback for local development:

bash

UNRAID_RMCP_HOST=127.0.0.1 runraid serve mcp

Use Docker Compose for shared HTTP deployment:

bash

cp .env.example .env
docker compose up -d

When binding to a non-loopback address, configure UNRAID_RMCP_TOKEN, UNRAID_RMCP_AUTH_MODE=oauth, or UNRAID_NOAUTH=true behind an authenticated gateway.

Troubleshooting

Symptom	Check
`UNRAID_API_URL` or `UNRAID_API_KEY` is missing	Set it in env or `~/.unraid/.env`.
TLS errors against Unraid	Set `UNRAID_API_SKIP_TLS_VERIFY=true` only for self-signed endpoints.
HTTP `/mcp` returns unauthorized	Set `UNRAID_RMCP_TOKEN` and send `Authorization: Bearer <token>`.
Stdio client hangs or logs JSON errors	Ensure client config runs `unraid-rmcp mcp`, not the default HTTP server mode.
Large list response is truncated	Use `limit`, `offset`, `name`, or `state` filters on MCP list actions.
`docker_logs` fails	Pass a valid container `id` and optional `tail`.

unifi-rmcp / rustifi - UniFi controller REST API bridge.
tailscale-rmcp / rustscale - Tailscale API bridge for devices, users, and tailnet operations.
apprise-rmcp - Apprise notification fan-out bridge for many delivery backends.
gotify-rmcp - Gotify push notification bridge for sends, messages, apps, and clients.
arcane-rmcp - Arcane Docker management bridge for containers and related resources.
yarr-rmcp - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.
ytdl-mcp - Media download and metadata workflow server.
synapse - Local Synapse workflow server for scout and flux actions.
cortex - Syslog and homelab log aggregation MCP server.
axon - RAG, crawl, scrape, extract, and semantic search project.
lab - Homelab control plane and Labby gateway project.
lumen - Local semantic code search MCP server.
nugs - Project/package management helper for local agent workflows.
agentcast - Agent transcript and activity publishing project.
soma - RMCP scaffold/runtime template for new provider-backed servers.

Documentation

CLAUDE.md is the curated local operating guide for contributors and agents.
docs/INVENTORY.md is the curated/generated inventory for actions, CLI commands, env vars, HTTP endpoints, and dependencies.
docs/stack/ARCH.md is the curated architecture guide.
docs/SETUP.md is curated plugin/setup guidance.
docs/OAUTH.md is curated OAuth setup guidance.
plugins/unraid/skills/unraid/SKILL.md is the agent usage guide.
src/ is the source of truth for current GraphQL queries, config defaults, auth behavior, and CLI parsing.

License

MIT. See LICENSE.

Install

Configuration

Environment variables

UNRAID_API_URLrequired

Full Unraid GraphQL endpoint URL.

UNRAID_API_KEYrequiredsecret

Unraid API key.

UNRAID_RMCP_VERSION

Optional GitHub release tag override for the downloaded Unraid RMCP binary.

UNRAID_RMCP_REPOdefault jmagar/unraid-rmcp

Optional GitHub owner/repo override for release asset downloads.

UNRAID_RMCP_RELEASE_BASE_URL

Optional release download base URL override.

RUST_LOGdefault info

Tracing filter for Unraid RMCP logs.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "unraid-rmcp": {
      "command": "npx",
      "args": [
        "-y",
        "unraid-rmcp@0.2.3",
        "mcp"
      ],
      "env": {
        "UNRAID_API_URL": "<YOUR_UNRAID_API_URL>",
        "UNRAID_API_KEY": "<YOUR_UNRAID_API_KEY>",
        "UNRAID_RMCP_VERSION": "<YOUR_UNRAID_RMCP_VERSION>",
        "UNRAID_RMCP_REPO": "jmagar/unraid-rmcp",
        "UNRAID_RMCP_RELEASE_BASE_URL": "<YOUR_UNRAID_RMCP_RELEASE_BASE_URL>",
        "RUST_LOG": "info"
      }
    }
  }
}

Topics

unraid-rmcp

Contents

Naming

Capabilities And Boundaries

Install

npm / npx

Build From Source

Quickstart

1. Configure Unraid

2. Run A Safe CLI Call

3. Start Loopback HTTP MCP

4. Make A First MCP Call

Client Configuration

Claude Code Stdio

Claude Code HTTP

Codex / Labby Gateway

Generic MCP JSON

Runtime Surfaces

MCP Tool Reference

Core Actions

System Actions

Log And Storage Actions

UPS, Remote, Plugin, And Meta Actions

CLI Reference

Configuration

Authentication

Safety And Trust Model

Architecture

Distribution Contract

Development

Verification

Deployment

Troubleshooting

Related Servers

Documentation

License

Install

Configuration