Unraid MCP

Ein lokaler Model Context Protocol-Server, der es KI-Clients ermöglicht, einen Unraid-Server über die offizielle GraphQL-API von Unraid zu inspizieren und zu verwalten.

Hinweis zur KI-gestützten Entwicklung: Dieses Projekt wurde mit erheblicher Unterstützung durch KI-Codierungsagenten entworfen, recherchiert, implementiert, dokumentiert und getestet. Es ist kein offizielles Unraid-Projekt. Prüfen Sie Quellcode, Berechtigungen und Sicherheitseinstellungen selbst, bevor Sie ihm Zugriff auf einen Unraid-Server gewähren – insbesondere bevor Sie Mutations-Tools aktivieren.

Der MCP ist standardmäßig schreibgeschützt. Mutierende Tools werden erst dann vollständig eingebunden, wenn sie explizit über Umgebungsvariablen aktiviert werden, und dauerhafte bzw. risikoreiche Aktionen verwenden ein zweites Sicherheitsgate.

Voraussetzungen

• Node.js 22 oder neuer

• pnpm 11

• Unraid 7.2 oder neuer, wobei die API im Betriebssystem integriert ist

• Ein Unraid-API-Schlüssel

Unraid 7.0–7.1 kann API v4 über das Unraid-Connect-Plugin bereitstellen, aber Unraid dokumentiert diese Kombination als eingeschränkt unterstützt. Die GraphQL-Dokumente in diesem Projekt zielen auf API v4.35.1, die mit Unraid 7.3.2 gebündelt ist. Ältere API-Versionen können neuere Abfragen wie Metriken, Logs oder UPS-Felder ablehnen.

Related MCP server: GraphQL MCP Toolkit

Unraid-Einrichtung

1. Öffnen Sie Einstellungen > Verwaltungszugriff > API-Schlüssel in der Unraid-WebGUI.

2. Erstellen Sie einen Schlüssel für diesen MCP.

3. Beginnen Sie mit der Rolle VIEWER für schreibgeschützten Zugriff.

4. Speichern Sie den generierten Schlüssel in UNRAID_API_KEY; legen Sie ihn niemals in der Versionskontrolle oder in Befehlszeilenargumenten ab.

Der entsprechende Unraid-Terminalbefehl lautet:

unraid-api apikey --create --name "Unraid MCP read only" --roles VIEWER --json

Für Mutationszugriff bevorzugen Sie feingranulare Berechtigungen gegenüber ADMIN. Wählen Sie nur die Ressourcen aus, die von den Tools verwendet werden, die Sie aktivieren möchten, z. B. ARRAY, DOCKER, VMS und NOTIFICATIONS, mit READ_ANY, UPDATE_ANY und nur wo nötig DELETE_ANY.

Die GraphQL-Sandbox ist für diesen MCP nicht erforderlich. Lassen Sie sie außerhalb der Entwicklung deaktiviert, da ihre Aktivierung auch die Schema-Introspection aktiviert.

Installation

pnpm install --frozen-lockfile
pnpm build

Abhängigkeiten sind exakt versionsgepinnt und Installationen sind lockfile-frozen. pnpm lehnt außerdem Veröffentlichungen ab, die vor weniger als sieben Tagen erschienen sind (einschließlich Paketen mit fehlenden Veröffentlichungszeiten), verifiziert die Paket-/Store-Integrität, blockiert nicht deklarierte Lifecycle-Skripte und verweigert Herabstufungen des Paketvertrauens. Die versionsspezifische Vertrauensausnahme für undici-types@6.21.0 wird vom gepinnten @types/node benötigt; Alters-, Integritäts- und Lockfile-Prüfungen gelten weiterhin dafür. Um eine Abhängigkeit nach Prüfung und Ablauf der Quarantänefrist absichtlich zu aktualisieren, verwenden Sie eine exakte Version und erlauben Sie die Lockfile-Änderung ausdrücklich:

pnpm update --exact --no-frozen-lockfile package-name@x.y.z
pnpm verify
pnpm audit

Prüfen Sie sowohl package.json als auch pnpm-lock.yaml, bevor Sie das Update akzeptieren. Fügen Sie keine automatisierten Abhängigkeitsaktualisierungs-Jobs hinzu, ohne diese Kontrollen beizubehalten.

Legen Sie die Konfiguration in der Umgebung fest, die den MCP startet:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"
node /absolute/path/to/unraid-mcp/dist/index.js

UNRAID_URL kann der WebGUI-Ursprung sein, in diesem Fall wird /graphql angehängt, oder der exakte GraphQL-Endpunkt. Konfigurieren Sie die endgültige HTTPS-URL direkt; Weiterleitungen werden abgelehnt, damit der API-Schlüssel nicht an einen anderen Ursprung weitergeleitet werden kann.

Container-Image

Versionierte Release-Images werden für linux/amd64 und linux/arm64 auf Docker Hub veröffentlicht. Pinnen Sie für Bereitstellungen eine Version oder einen Image-Digest, anstatt sich auf das veränderliche latest-Tag zu verlassen:

docker pull lemanjo/unraid-mcp:0.1.1

Das endgültige Image verwendet eine digest-gepinnte Distroless-Node.js-Laufzeit. Es läuft ohne Shell, Paketmanager, npm oder andere Build-Werkzeuge und als numerischer Nicht-Root-Benutzer. Container-Builds werden mit Trivy gescannt und schlagen vor dem Registry-Login fehl, wenn eine behebbare kritische oder hohe Schwachstelle vorhanden ist.

Erstellen Sie das Produktionsimage auf Ihrem Unraid-Server oder einem anderen Docker-Host:

docker build --tag unraid-mcp:0.1.1 .

Lokaler stdio-Container

Der Standardtransport ist stdio. --env NAME leitet Werte aus der startenden Umgebung weiter, ohne Geheimnisse in das Image oder in Befehlsargumente zu legen:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

Leiten Sie optionale Konfiguration auf dieselbe Weise weiter, z. B. --env UNRAID_ALLOW_MUTATIONS. Für eine benutzerdefinierte CA-Datei mounten Sie sie schreibgeschützt und konfigurieren Sie ihren Containerpfad:

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  --env UNRAID_CA_CERT_PATH=/certs/unraid-ca.pem \
  --volume /host/path/unraid-ca.pem:/certs/unraid-ca.pem:ro \
  unraid-mcp:0.1.1

Im stdio-Modus lauscht das Image nicht auf einem Port. Der KI-Host startet es mit docker run --rm -i und besitzt seine Lebensdauer.

Immer aktiver Remote-HTTP-Container

Verwenden Sie authentifiziertes Streamable HTTP, wenn der Container auf einem anderen Rechner als der KI-Client läuft. Generieren Sie ein persistentes MCP-Token auf einem vertrauenswürdigen Rechner:

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-unraid-api-key"
export MCP_ALLOWED_HOSTS="mcp-server.example,192.168.1.20"

Starten Sie den Remote-Container:

docker network create unraid-mcp-backend

docker run -d \
  --name unraid-mcp \
  --restart unless-stopped \
  --network unraid-mcp-backend \
  --env MCP_TRANSPORT=http \
  --env MCP_HOST=0.0.0.0 \
  --env MCP_PORT=3000 \
  --env MCP_ALLOWED_HOSTS \
  --env MCP_AUTH_TOKEN \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

MCP_ALLOWED_HOSTS ist zwingend erforderlich, wenn eine IPv4- oder IPv6-Wildcard-Adresse gebunden wird. Listen Sie jeden Hostnamen oder jede IP-Adresse auf, die Clients oder ein Reverse-Proxy in den HTTP-Host-Header setzen. Einträge enthalten keine Ports, und IPv6-Einträge verwenden eckige Klammern. Localhost-Werte sind für Health-Checks immer enthalten.

Wenn MCP_AUTH_TOKEN weggelassen wird, generiert der Server ein kryptographisch zufälliges 256-Bit-Token und gibt es beim Start einmal aus:

docker logs unraid-mcp

Achten Sie auf Generated MCP auth token:. Jeder, der dieses Log lesen kann, hat Zugriff auf den MCP, und nach jedem Prozessneustart wird ein neues Token generiert, wenn die Variable nicht gesetzt ist. Setzen Sie MCP_AUTH_TOKEN für stabile Produktionsbereitstellungen explizit. Das MCP-Token ist getrennt von UNRAID_API_KEY; entfernte KI-Clients benötigen nur das MCP-Token.

Der HTTP-Listener ist absichtlich einfaches HTTP. Das Beispiel veröffentlicht seinen Port nicht; verbinden Sie einen Caddy-, Nginx- oder Traefik-Container mit unraid-mcp-backend und proxen Sie an http://unraid-mcp:3000. Für einen hostinstallierten Proxy kann Docker 28 oder neuer 127.0.0.1:3000:3000 veröffentlichen; ältere Docker-Versionen, einschließlich einiger Unraid-Versionen, können lokal veröffentlichte Ports im selben Layer-2-Netzwerk verfügbar machen. Verwenden Sie daher stattdessen das private Netzwerk oder eine explizite Firewall-Regel. Setzen Sie Port 3000 nicht direkt dem Internet aus. Der Container-Health-Check ruft GET /health auf; MCP-Datenverkehr verwendet /mcp.

Die integrierte Authentifizierungs-Drosselung identifiziert den unmittelbaren TCP-Peer. Hinter einem Reverse-Proxy konfigurieren Sie die Authentifizierungs-Ratenbegrenzung auch am Proxy, da alle proxied Clients eine gemeinsame Peer-Adresse haben können. Leiten Sie keinen unvertrauenswürdigen Host-Wert weiter; bewahren Sie entweder den externen Hostnamen auf und nehmen Sie ihn in MCP_ALLOWED_HOSTS auf, oder schreiben Sie ihn auf einen festen, auf der Whitelist stehenden Hostnamen um.

Lokale Docker-Client-Konfiguration

Eine OpenCode-Konfiguration, die das Image über einen Docker-Daemon startet, lautet:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}"
      }
    }
  }
}

Der vom KI-Host verwendete Docker-Daemon muss Zugriff auf das Image haben. Starten Sie OpenCode nach einer Änderung seiner Konfiguration neu.

Konfiguration

Verwenden Sie entweder UNRAID_CA_CERT oder UNRAID_CA_CERT_PATH, nicht beides. Bevorzugen Sie das Vertrauen in das Unraid-Zertifikat oder die lokale CA. UNRAID_TLS_SKIP_VERIFY=true ist eine explizite letzte Option und gibt eine Warnung aus; es ändert das TLS-Verhalten nicht global für andere Node.js-Verbindungen.

Einfaches HTTP wird für isolierte Legacy-Netzwerke unterstützt, gibt aber eine Warnung aus, da der API-Schlüssel und alle Serverdaten unverschlüsselt übertragen werden.

KI-Client-Einrichtung

OpenCode

Exportieren Sie die Umgebungsvariablen, bevor Sie OpenCode starten, und fügen Sie dann diesen lokalen MCP zu opencode.json hinzu:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": ["node", "/absolute/path/to/unraid-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}",
        "UNRAID_CA_CERT_PATH": "{env:UNRAID_CA_CERT_PATH}",
        "UNRAID_ALLOW_MUTATIONS": "{env:UNRAID_ALLOW_MUTATIONS}",
        "UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS": "{env:UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS}"
      }
    }
  }
}

Entfernen Sie optionale Umgebungseinträge, die nicht gesetzt sind. Starten Sie OpenCode nach einer Änderung seiner Konfiguration neu.

Um eine Verbindung zu einem immer aktiven HTTP-Container herzustellen, exportieren Sie dessen MCP-Token auf dem OpenCode-Rechner und konfigurieren Sie einen Remote-Server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "remote",
      "url": "https://mcp-server.example/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MCP_AUTH_TOKEN}"
      }
    }
  }
}

Verwenden Sie die HTTPS-Reverse-Proxy-URL, nicht die Unraid-GraphQL-URL. OpenCode sendet MCP_AUTH_TOKEN an den MCP; nur der MCP-Container sendet UNRAID_API_KEY an Unraid.

Claude Code

Exportieren Sie UNRAID_URL und UNRAID_API_KEY, bevor Sie Claude Code starten. Für den Projektbereich erstellen Sie .mcp.json in dem Projekt, in dem Sie Claude Code verwenden:

{
  "mcpServers": {
    "unraid": {
      "command": "node",
      "args": ["/absolute/path/to/unraid-mcp/dist/index.js"],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Claude Code expandiert die ${VAR}-Referenzen aus seiner Umgebung. Die Konfiguration kann daher geteilt werden, ohne den API-Schlüssel zu speichern. Fügen Sie optionale Variablen zu env nur hinzu, wenn sie gesetzt sind, z. B. "UNRAID_ALLOW_MUTATIONS": "${UNRAID_ALLOW_MUTATIONS}".

Um stattdessen das Container-Image zu starten, verwenden Sie:

{
  "mcpServers": {
    "unraid": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Führen Sie claude mcp list aus, um den Server zu verifizieren, und verwenden Sie dann /mcp in Claude Code, um seinen Status und seine Tools zu prüfen. Claude Code fragt vor der Verwendung eines projektspezifischen .mcp.json-Servers um Genehmigung. Verwenden Sie --scope user mit den MCP-Befehlen von Claude Code, wenn Sie eine private projektübergreifende Konfiguration in ~/.claude.json bevorzugen.

Für einen immer aktiven HTTP-Container verwenden Sie stattdessen diesen .mcp.json-Eintrag:

{
  "mcpServers": {
    "unraid": {
      "type": "http",
      "url": "https://mcp-server.example/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Exportieren Sie MCP_AUTH_TOKEN, bevor Sie Claude Code starten. Die ${MCP_AUTH_TOKEN}-Referenz wird expandiert, ohne ihren Wert in der Projektkonfiguration zu speichern.

Codex CLI und IDE

Codex CLI, die Codex-IDE-Erweiterung und die ChatGPT-Desktop-App teilen sich die MCP-Konfiguration. Exportieren Sie die erforderlichen Variablen und fügen Sie dann diesen Eintrag zu ~/.codex/config.toml oder zu .codex/config.toml in einem vertrauenswürdigen Projekt hinzu:

[mcp_servers.unraid]
command = "node"
args = ["/absolute/path/to/unraid-mcp/dist/index.js"]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

env_vars leitet Werte aus der Codex-Umgebung weiter, ohne sie in config.toml zu schreiben. Fügen Sie alle aktivierten optionalen Einstellungen zu dieser Liste hinzu, z. B. UNRAID_CA_CERT_PATH oder UNRAID_ALLOW_MUTATIONS.

Um stattdessen das Container-Image zu starten, verwenden Sie:

[mcp_servers.unraid]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "--env",
  "UNRAID_URL",
  "--env",
  "UNRAID_API_KEY",
  "unraid-mcp:0.1.1",
]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Der writes-Genehmigungsmodus fragt bei Tools, die nicht als schreibgeschützt markiert sind, nach einer Bestätigung. Führen Sie codex mcp list aus, um den Server zu überprüfen, und verwenden Sie /mcp in der Codex-TUI, um die verbundenen Tools zu inspizieren. Starten Sie die IDE-Erweiterung oder die ChatGPT-Desktop-App neu, nachdem Sie die gemeinsame Konfiguration bearbeitet haben.

Für einen dauerhaft laufenden HTTP-Container verwenden Sie stattdessen diesen Eintrag:

[mcp_servers.unraid]
url = "https://mcp-server.example/mcp"
bearer_token_env_var = "MCP_AUTH_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Codex liest das Bearer-Token aus seiner lokalen Umgebung und speichert den Wert nicht in config.toml.

Claude Desktop und andere Stdio-Hosts

Konfigurieren Sie den Host, damit er Folgendes startet:

node /absolute/path/to/unraid-mcp/dist/index.js

Lassen Sie den Hostprozess die erforderlichen Umgebungsvariablen vom Betriebssystem, einem Dienst-Manager oder dessen Secret-Manager erben. Legen Sie den API-Schlüssel nicht im args-Array ab. Falls ein Host pro Server konfigurierbare Umgebungswerte, aber keine Secret-Referenzen unterstützt, beachten Sie, dass diese Werte in der Konfigurationsdatei des jeweiligen Hosts gespeichert werden.

MCP Inspector

Mit den exportierten Variablen lassen sich Tools interaktiv inspizieren und aufrufen:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js

Der Inspector ist bewusst keine Projektabhängigkeit; verwenden Sie die für Ihre Umgebung freigegebene Version.

Tools

Die folgenden Nur-Lese-Tools sind immer registriert:

Mit UNRAID_ALLOW_MUTATIONS=true kommen hinzu:

Mit UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS=true kommen zusätzlich hinzu:

Außerdem wird dadurch ermöglicht, unraid_control_parity_check mit correct=true zu starten.

MCP-Anmerkungen sind Hinweise für Clients, keine Zugriffskontrollen. Die eigentlichen Kontrollen sind die Umgebungs-Gates und die Berechtigungen des Unraid-API-Schlüssels selbst.

API-Einschränkungen

Das aktuelle offizielle Schema stellt nicht jede WebGUI-Aktion bereit. Insbesondere:

• Shares sind schreibgeschützt; das Erstellen/Bearbeiten von Shares ist nicht verfügbar.

• Docker-Container können gesteuert, aktualisiert und entfernt, aber nicht erstellt oder bearbeitet werden.

• VMs können gesteuert, aber nicht erstellt, bearbeitet, geklont, gesnapshottet oder gelöscht werden.

• Mutationen zum Herunterfahren/Neustarten des Hosts sind nicht veröffentlicht.

• Vollständige SMART-Berichte und SMART-Selbsttest-Steuerungen sind nicht veröffentlicht.

• Docker restart wurde nach API v4.35.1 hinzugefügt und wird von diesem Kompatibilitätsziel absichtlich nicht verwendet.

• Antworttypen für Paritätsmutationen sind von Unraid als Work-in-Progress markiert.

Siehe docs/api-capabilities.md für die offiziellen Quellenangaben und Kompatibilitätsdetails.

Entwicklung

pnpm typecheck
pnpm test
pnpm build
# Or run all three:
pnpm verify

Tests verwenden lokale Mock-HTTP-Server sowie In-Memory- und Streamable-HTTP-MCP-Clients. Sie benötigen weder Docker noch einen laufenden Unraid-Server.

Container-Veröffentlichungen

GitHub Actions erstellt den Container für Pull Requests und Änderungen an main und führt einen Schwachstellenscan durch, ohne Registry-Anmeldedaten zu verwenden. Veröffentlicht wird nur, wenn ein semantisch versioniertes GitHub-Release wie v0.1.1 veröffentlicht wird. Der Release-Workflow scannt das erstellte Image, bevor er auf das DOCKERHUB_TOKEN der geschützten Umgebung dockerhub zugreift, und veröffentlicht dann Version-, Commit- und (bei stabilen Releases) latest-Tags mit SBOM- und Provenienz-Bescheinigungen.

Sicherheitshinweise

• Stdio bleibt der Standard und öffnet keinen lauschenden Netzwerkport.

• Der HTTP-Modus erfordert Bearer-Authentifizierung. Fehlende Tokens werden mit 256 Bit kryptografischer Zufälligkeit erzeugt und bewusst in die Startprotokolle geschrieben.

• Erzeugte Tokens sind operative Geheimnisse: Schränken Sie den Protokollzugriff ein und konfigurieren Sie für eine stabile Bereitstellung MCP_AUTH_TOKEN.

• Der HTTP-Modus validiert Host- und Origin-Header, begrenzt fehlgeschlagene Authentifizierungsversuche per Rate-Limit, begrenzt die Anforderungstexte und bindet standardmäßig an Loopback.

• Der eingebaute HTTP-Listener bietet kein TLS. Verwenden Sie einen HTTPS-Reverse-Proxy und setzen Sie ihn nicht direkt dem Internet aus.

• Er schreibt niemals Anwendungsprotokolle nach stdout, das für MCP JSON-RPC reserviert ist.

• Er zeigt nicht, akzeptiert keine beliebigen GraphQL-Dokumente vom Modell.

• Er folgt keinen Weiterleitungen und begrenzt Antwortgröße, Anzahl der Protokollzeilen und Dauer der Anforderungen.

• Ein Client-Abbruch bricht die lokale HTTP-Anforderung ab; Mutationen, die Unraid bereits angenommen hat, können nicht rückgängig gemacht werden.

• GraphQL-Fehler werden geschwärzt, wenn sie den konfigurierten API-Schlüssel enthalten.

• Festplatten-Seriennummern, Protokolle, Benachrichtigungen, Netzwerkadressen und andere Serverdaten sind für den verbundenen KI-Client sichtbar. Überprüfen Sie die Datenverarbeitungsrichtlinie dieses Clients.

Offizielle Referenzen

• Unraid-API-Überblick

• So verwenden Sie die Unraid-API

• Verwaltungsprogramm für API-Schlüssel

• Fahrplan und Versionsunterstützung der Unraid-API

• API v4.35.1 generiertes GraphQL-Schema

• Leitfaden zur Absicherung der Unraid-Verbindung

• Anleitung für MCP TypeScript SDK stdio

• Anleitung für MCP TypeScript SDK Streamable HTTP

• MCP-Konfiguration für Claude

• MCP-Konfiguration in Codex

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.