Frag deine KI über dein Netzwerk — der DeviceShelf-MCP-Server

Ab Server-Edition 1.5.3 beantwortet DeviceShelf Fragen zu deinem Netzwerk in normaler Sprache. Es macht sein Live-Inventar und seinen Monitoring-Zustand einer KI wie Claude Desktop zugänglich, über das Model Context Protocol (MCP). Frag „Was ist gerade online?“, „Was ist seit gestern neu oder offline?“, „Welche Geräte haben bald ablaufende Zertifikate?“ oder „Wie unterscheidet sich das Netz von heute vom Snapshot letzter Woche?“ und die KI antwortet aus deinen eigenen Daten.

Insgesamt sind das 22 Tools (14 lesend, 8 Opt-in-Aktionen), 3 geführte Prompts, 4 anhängbare Resources und ein optionaler Live-Modus, der Änderungen direkt an den Client pusht.

Strikt lokal

Der MCP-Endpunkt läuft innerhalb deines DeviceShelf-Servers, auf demselben Port wie die API, hinter einem Bearer-Token, erreichbar nur in deinem LAN. Nichts geht an einen externen Dienst, außer über den KI-Client, den du verbindest; es gibt keinen DeviceShelf-Cloud-Connector und kein Remote-OAuth. Er liest dieselben In-Process-Daten wie das Dashboard, die KI-Sicht kann also nie von dem abweichen, was du siehst.

Was er beantworten kann

Die nur-lesenden Tools decken die gesamte Monitoring-Oberfläche ab:

Inventar: network_summary für die Übersicht auf einen Schlag (Subnetz, Gateway, Geräte- und Alarmzahlen), list_devices mit Filtern und Pagination (online/Typ/Subnetz/Favorit/Tag), find_device als Freitextsuche („der Drucker“, „mein NAS“), get_device mit vollen Details pro Gerät (offene Ports, OS, SNMP, TLS, gematchte CVEs, Notizen) und list_interfaces für Multi-NIC-Collectors.
Monitoring: list_changes (jüngste Timeline: neu/online/offline/Port-Änderungen), list_alarms (aktueller Alarmzustand und Quittierung), list_checks (deine konfigurierten Monitor-Checks samt aktuellem Zustand), get_device_history (Online/Offline- und RTT-Verlauf), get_device_uptime (Uptime/SLA pro Gerät über bis zu 90 Tage) und list_offline_devices („was ist verschwunden?“).
Sicherheit: Ein einziger security_overview-Aufruf zeigt bald ablaufende oder bereits abgelaufene Zertifikate, self-signed Zertifikate und Geräte mit bekannten CVEs nach Schweregrad, netzweit und ohne Abfrage pro Host.
Snapshots: list_snapshots und diff_snapshots vergleichen zwei benannte Aufnahmen deines Netzes, oder eine Aufnahme mit dem Live-Scan: hinzugekommene Geräte, verschwundene Geräte, Port-Änderungen. „Was ist neu seit dem Audit im Mai?“ wird zu einer einzigen Frage.

Opt-in-Aktionen

Mit einem zweiten, separaten Opt-in (DEVICESHELF_MCP_ALLOW_ACTIONS=true) erhält die KI zusätzlich Aktions-Tools:

set_device_metadata: Gerät umbenennen, Typ oder Kommentar setzen („nenn das mit :4e am Ende ‚Thermostat Wohnzimmer‘“).
acknowledge_alarm: einen aktiven Alarm direkt aus dem Gespräch quittieren.
save_check / delete_check: Monitor-Checks (ping/tcp/http/snmp) in normaler Sprache anlegen oder ändern. „Überwache mein NAS per HTTP und alarmiere mich, wenn es down ist“ wird ein laufender Check.
save_snapshot: den aktuellen Netzzustand als benannten Snapshot festhalten, für spätere Vergleiche.
scan_now und port_check: einen Scan anstoßen oder TCP-Ports eines Hosts prüfen, beschränkt auf deine eigenen lokal angebundenen Subnetze und rate-limitiert.
test_notification: den Alarmkanal Ende-zu-Ende testen.

Optional sorgt DEVICESHELF_MCP_CONFIRM_ACTIONS=true dafür, dass die eingriffsstarken Aktionen erst eine Bestätigung beim Client einholen (MCP-Elicitation). Ein Scan startet also nie, ohne dass du auf Ja klickst.

Prompts und Resources

Für Nicht-Experten liefert der Server geführte Prompts mit, die im Prompt-Picker des Clients erscheinen: Sicherheits-Audit (ein priorisierter Risikobericht), Was hat sich zuletzt geändert und Unbekannte Geräte identifizieren. Ein Klick genügt für eine brauchbare Antwort, ganz ohne Tool-Namen.

Außerdem gibt es vier nur-lesende Resources (deviceshelf://network/summary, deviceshelf://devices, deviceshelf://alarms, deviceshelf://security/overview), die ein Client ohne Tool-Aufruf als Kontext anhängen kann.

Live-Modus

Standardmäßig arbeitet der Endpunkt zustandslos im Frage-Antwort-Muster. Mit DEVICESHELF_MCP_LIVE=true wechselt er auf zustandsbehaftete Sessions: Clients können die Geräte-, Alarm- und Übersichts-Resources abonnieren und bekommen resources/updated-Benachrichtigungen gepusht, sobald sich das Inventar ändert. Die KI bleibt aktuell, ohne zu pollen. Inaktive Sessions schließen nach 30 Minuten.

Gebaut wie ein Sicherheits-Feature

Eine KI, die dein Netzwerk-Inventar liest, verdient dieselbe Sorgfalt wie jeder andere Client, deshalb:

/mcp ist auth-pflichtig, genau wie die API: ohne Token keine Antwort.
Ein Scoped Token (DEVICESHELF_MCP_TOKEN) gilt nur für /mcp, nie für die Admin-API oder Metrics. Dein KI-Client muss nie ein Admin-Credential halten.
Schreibaktionen sind ab Werk aus, und die sondierenden Aktionen bleiben auch aktiviert auf lokale Subnetze beschränkt.
Alle Tool-Aufrufe sind rate-limitiert (Token-Bucket, Standard 300/min) und werden auditiert: Tool-Name und Ergebnis, nie die Argumente.
Von Geräten gemeldete Strings (Hostnamen, Banner, Zertifikats-Namen) gelten als nicht vertrauenswürdige Eingabe: Steuer- und Text-Spoofing-Zeichen (Bidi, Zero-Width) werden entfernt und Werte gekürzt, bevor sie die KI erreichen. Das Modell wird zudem angewiesen, sie als Daten zu behandeln.
Eine Origin-Allowlist schützt gegen DNS-Rebinding aus dem Browser.

Aktivieren

In /etc/deviceshelf/server.env (oder deiner Docker-Umgebung):

DEVICESHELF_MCP_ENABLE=true

Server neu starten. Der Endpunkt liegt unter http://<dein-server>:8088/mcp und erwartet den Bearer-Token. Um Claude Desktop zu verbinden, nutze mcp-remote als Brücke. Behalte --allow-http bei (der Endpunkt ist plain http im LAN) und übergib den Token über eine Env-Variable, das umgeht einen Windows-Quoting-Bug:

{
  "mcpServers": {
    "deviceshelf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://<dein-server>:8088/mcp",
               "--transport", "http-only", "--allow-http",
               "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer <dein-token>" }
    }
  }
}

Jeder MCP-Client, der Streamable HTTP spricht, kann sich direkt verbinden. Verifizierte Copy-Paste-Configs für Claude Code, Cursor, VS Code, Windsurf, Cline und Gemini CLI stehen im „Connect your AI agent“-Guide; die vollständige Konfigurationsreferenz (Scoped Token, Aktions-Gate, Rate-Limit, Live- und Bestätigungs-Modus) steht auf der Server-Seite.

In deiner Lizenz enthalten

MCP ist Teil der Server-Edition, kein separater Kauf. Es funktioniert während der 7-tägigen Testphase, damit du es evaluieren kannst; nach Ablauf einer unlizenzierten Testphase antwortet der Endpunkt mit 402.

Kompatibilität

Verfügbar ab deviceshelf-server 1.5.3 (Docker-Image ghcr.io/wealthwallet/deviceshelf-server:1.5.3, .deb oder jedes neuere Release). Standardmäßig aus und rein additiv: Bestehende Server sind unberührt, bis du DEVICESHELF_MCP_ENABLE setzt. Dein Feedback bestimmt, welche Tools als Nächstes kommen — melde dich.