truenas-mcp

Ein NAS in einen KI-Assistenten einzubinden bedeutet normalerweise, ein MCP-Tool pro Operation zu registrieren. TrueNAS SCALE richtig abzudecken ergibt 50–80 Tool-Schemas – etwa 28.000 Tokens deines Kontextfensters, die verbraucht werden, bevor das Modell ein einziges Wort deiner Frage gelesen hat, bei jeder Anfrage, ob du nun Speicher anfasst oder nicht.

truenas-mcp deckt 278 Aktionen in 18 Kategorien ab – die gesamte TrueNAS-SCALE-REST-API – hinter einem hierarchischen Tool, das etwa 200 Tokens kostet. Das Modell fragt, welche Kategorien existieren, bohrt sich in die benötigte hinein und ruft dann die Aktion auf. Destruktive Operationen weigern sich, ohne confirm: true ausgeführt zu werden.

Installation (60 Sekunden)

# No install needed
TRUENAS_URL=https://truenas.local TRUENAS_API_KEY=1-abc123 npx truenas-mcp

Claude Code:

claude mcp add truenas -- npx -y truenas-mcp   --env TRUENAS_URL=https://truenas.local   --env TRUENAS_API_KEY=1-your-api-key-here

Hole den API-Schlüssel aus der TrueNAS-Oberfläche: Einstellungen > API-Schlüssel > Hinzufügen.

Related MCP server: Proxmox MCP Server

So sieht es aus

Du: „Sind meine Pools gesund, und kannst du eine NFS-Freigabe für das Media-Dataset erstellen?“

→ truenas({ category: "storage", action: "pool_list" })
  tank — ONLINE, 68% used, 0 errors

→ truenas({ category: "sharing", action: "nfs_share_create",
            params: { path: "/mnt/tank/media", comment: "Media share" } })

Das Modell hat nfs_share_create entdeckt, indem es zuerst truenas({ category: "sharing" }) aufgerufen hat – es hatte diese 36 Sharing-Aktionen nie in seinem Prompt.

Warum ein Tool statt 278

Vollständige Konfiguration

# Using npx (no install needed)
TRUENAS_URL=https://truenas.local TRUENAS_API_KEY=1-abc123 npx truenas-mcp

# Or install globally
npm install -g truenas-mcp

Umgebungsvariablen

Claude-Desktop-Konfiguration

Füge Folgendes zu deiner claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "truenas": {
      "command": "npx",
      "args": ["-y", "truenas-mcp"],
      "env": {
        "TRUENAS_URL": "https://truenas.local",
        "TRUENAS_API_KEY": "1-your-api-key-here",
        "TRUENAS_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Code

claude mcp add truenas -- npx -y truenas-mcp \
  --env TRUENAS_URL=https://truenas.local \
  --env TRUENAS_API_KEY=1-your-api-key-here \
  --env TRUENAS_VERIFY_SSL=false

So funktioniert es – Hierarchisches Tool-Design

Statt 278 einzelne Tools zu registrieren (was ~30.000 Tokens im LLM-Systemprompt verbrauchen würde), stellt dieser Server ein Tool namens truenas mit drei Verwendungsmodi bereit:

1. Kategorien entdecken

truenas()

Gibt alle 18 Kategorien mit Beschreibungen und Aktionsanzahlen zurück (~200 Tokens).

2. Eine Kategorie erkunden

truenas({ category: "storage" })

Gibt alle Aktionen in dieser Kategorie mit ihren erforderlichen/optionalen Parametern zurück.

3. Eine Aktion ausführen

truenas({ category: "storage", action: "pool_list" })
truenas({ category: "storage", action: "dataset_create", params: { name: "tank/media", compression: "LZ4" } })

Das bedeutet, dass das LLM nur die Token-Kosten für das bezahlt, was es tatsächlich nutzt.

Kategorien

MCP-Ressourcen (12)

Schreibgeschützte Ressourcen für Dashboards – kein Tool-Aufruf nötig:

Beispielkonversationen

„Welche Pools habe ich und sind sie gesund?“

→ truenas({ category: "storage", action: "pool_list" })

„Erstelle eine NFS-Freigabe für /mnt/tank/media“

→ truenas({ category: "sharing", action: "nfs_share_create", params: { path: "/mnt/tank/media", comment: "Media share" } })

„Prüfe auf Systemupdates“

→ truenas({ category: "update", action: "update_check" })

„Welche SMART-Tests wurden auf sda ausgeführt?“

→ truenas({ category: "disk", action: "disk_smart_test_list", params: { disk: "sda" } })

Sicherheit

Alle destruktiven Operationen erfordern confirm: true in den Parametern:

• Pool erstellen/exportieren/Festplatte ersetzen

• Dataset/Snapshot löschen, Snapshot-Rollback

• VM löschen, App löschen/Rollback

• System neu starten/herunterfahren, Update anwenden

• Festplatte löschen, Boot-Festplatte anhängen/abhängen

• Zertifikat löschen, Boot-Umgebung löschen

• Verzeichnisdienste verlassen, ACL setzen

Ohne confirm: true geben diese Aktionen eine Fehlermeldung zurück, die erklärt, was passieren würde.

API-Kompatibilität

Entwickelt für die TrueNAS SCALE REST-API v2.0. Kompatibel mit TrueNAS SCALE 22.x bis 25.x.

Entwicklung

git clone https://github.com/spranab/truenas-mcp
cd truenas-mcp
npm install
npm run build
npm run dev  # watch mode

Verwandte Projekte

Andere MCP-Server und Agent-Infrastruktur vom selben Autor:

• mcpier – selbst gehostete MCP-Kontrollebene für dein Homelab; hält API-Schlüssel von deinen Clients fern.

• saga-mcp – SQLite-gestützter Projekt-Tracker, damit der Agent den Plan zwischen Sitzungen nicht verliert.

• yantrikdb-mcp – persistentes kognitives Gedächtnis für Claude Code, Cursor und Windsurf.

• swarmcode – Echtzeitkanal zwischen Claude-Code-Instanzen auf verschiedenen Maschinen.

• brainstorm-mcp – Multi-Modell-Debatte als MCP-Tool.

Lizenz

MIT