talos-mcp

Release Go Reference codecov Go Report Card OpenSSF Scorecard License

Ein MCP-Server, der die Verwaltung von Talos Linux-Clustern für KI-Agenten (Claude Code, OpenAI Codex und jeden MCP-kompatiblen Client) zugänglich macht. Anstatt talosctl-Ausgaben in den Chat zu kopieren, ruft der Agent strukturierte Tools auf, die maschinenlesbares JSON direkt von der Talos gRPC-API zurückgeben – ohne Token-Kosten für Zwischenausgaben.

Verbindet sich über die native Talos gRPC-API mit Ihrem Cluster unter Verwendung derselben mTLS-Anmeldedaten wie talosctl (~/.talos/config).

Installation

Via npm (kein Go erforderlich, Linux/macOS, amd64/arm64):

npx talos-mcp

Binärdatei herunterladen (Linux/macOS, amd64/arm64):

Laden Sie das neueste Release von GitHub Releases herunter, entpacken Sie es und legen Sie die Binärdatei in Ihrem $PATH ab.

Aus dem Quellcode bauen (erfordert Go 1.21+):

git clone https://github.com/Nosmoht/talos-mcp-server
cd talos-mcp
go build -o talos-mcp .

Konfiguration

Liest standardmäßig ~/.talos/config (dieselbe Datei, die talosctl verwendet). Überschreiben Sie dies über Umgebungsvariablen:

Variable	Standardwert	Beschreibung
`TALOSCONFIG`	`~/.talos/config`	Pfad zur talosconfig-Datei
`TALOS_CONTEXT`	aktiver Kontext	Zu verwendender Kontextname
`TALOS_ENDPOINTS`	aus Konfiguration	Kommagetrennte Endpunkt-Überschreibungen
`TALOS_MCP_READ_ONLY`	`false`	Auf `true` setzen, um alle mutierenden Tools beim Start zu deaktivieren
`TALOS_MCP_ALLOWED_PATHS`	(alle)	Kommagetrennte Pfadpräfixe, die für `talos_read_file` und `talos_list_files` erlaubt sind (z. B. `/etc,/proc`)
`TALOS_MCP_SKIP_VERSION_CHECK`	`false`	Auf `true` setzen, um die Validierung des Upgrade-Pfads zu umgehen (z. B. für Factory-Images oder benutzerdefinierte Tags)

Kompatibilität

Dieser Server wurde mit Talos Linux v1.9.x bis v1.12.x getestet.

talos-mcp	Talos Linux	machinery SDK
v0.x (aktuell)	v1.9.0 – v1.12.x	v1.12.6

Der Server protokolliert eine Startwarnung, wenn die Talos-Version des verbundenen Clusters außerhalb des getesteten Bereichs liegt. Alle 19 verwendeten gRPC-Methoden sind seit Talos v1.9 stabil.

Validierung des Upgrade-Pfads

Das Tool talos_upgrade validiert, ob die Zielversion dem unterstützten Upgrade-Pfad von Talos folgt – maximal eine Minor-Version auf einmal (z. B. v1.11.x → v1.12.x). Upgrades, die Minor-Versionen überspringen, werden mit einem Fehler abgelehnt.

Wenn Ihr Image ein benutzerdefiniertes oder Factory-Tag verwendet (z. B. factory.talos.dev/... oder :latest), kann das Tag nicht geparst werden und die Validierung wird automatisch übersprungen. Um die Validierung explizit zu umgehen, setzen Sie TALOS_MCP_SKIP_VERSION_CHECK=true.

Client-Einrichtung

Claude Code

Fügen Sie dies zur .mcp.json Ihres Projekts hinzu:

{
  "mcpServers": {
    "talos": {
      "command": "npx",
      "args": ["-y", "talos-mcp"]
    }
  }
}

Oder global in ~/.claude.json unter "mcpServers". Wenn Sie eine lokale Binärdatei bevorzugen, ersetzen Sie "command": "npx" durch den Pfad zur Binärdatei.

Claude Desktop

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "talos": {
      "command": "npx",
      "args": ["-y", "talos-mcp"]
    }
  }
}

OpenAI Codex

Fügen Sie dies zu .codex/config.toml (Projekt) oder ~/.codex/config.toml (global) hinzu:

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

[mcp_servers.talos.env]
TALOSCONFIG = "/path/to/talosconfig"

Generischer MCP-Client

Der Server spricht das MCP-Protokoll über stdio:

./talos-mcp

Tools

Nur-Lese-Tools

Tool	Beschreibung
`talos_resource_definitions`	Listet alle verfügbaren Ressourcentypen und deren Aliase auf. Rufen Sie dies zuerst auf, um zu erfahren, was abgefragt werden kann.
`talos_get`	Ruft eine beliebige COSI-Ressource nach Typ ab oder listet sie auf (z. B. `MachineStatus`, `Member`, `NodeAddress`, `Service`).
`talos_version`	Ruft Talos-Versionsinformationen von Zielknoten ab.
`talos_services`	Listet alle Talos-Dienste und deren aktuellen Status auf (laufend, gestoppt, gesund).
`talos_containers`	Listet Container in einem Namespace auf (Standard: `k8s.io` für Kubernetes-Container).
`talos_processes`	Listet laufende Prozesse auf Zielknoten auf.
`talos_health`	Überprüft den Cluster-Status (etcd, Kubernetes API, Knotenbereitschaft). Unterstützt `control_plane_nodes` / `worker_nodes` Überschreibung.
`talos_logs`	Ruft aktuelle Dienstprotokolle ab (letzte N Zeilen, kein Follow).
`talos_dmesg`	Liest Kernel-Ringpuffer-Meldungen.
`talos_events`	Ruft aktuelle Talos-Laufzeitereignisse ab (Dienständerungen, Konfigurationsänderungen).
`talos_etcd`	Fragt den etcd-Cluster ab: `members` (Standard) oder `status`.
`talos_list_files`	Listet Dateien und Verzeichnisse auf einem Knoten-Dateisystem auf.
`talos_read_file`	Liest Dateiinhalte von einem Knoten-Dateisystem.

Mutierende Tools

Diese Tools ändern den Cluster-Status und verfügen über explizite Sicherheitsvorkehrungen.

Tool	Beschreibung	Sicherheitsvorkehrungen
`talos_service_action`	Startet, stoppt oder startet einen Talos-Dienst neu (Hinweis: der Neustart von `etcd` wird von der Talos-API nicht unterstützt).	—
`talos_reboot`	Startet Zielknoten neu. Unterstützt `mode`: `default`, `powercycle`, `force`.	`confirm=true` erforderlich; `nodes` müssen explizit angegeben werden
`talos_upgrade`	Führt ein Upgrade von Talos auf Zielknoten durch. Unterstützt `preserve` (Standard `true`), `stage`, `force`, `reboot_mode`.	`confirm=true` erforderlich; `nodes` und `image` erforderlich
`talos_rollback`	Führt ein Rollback des letzten Upgrades auf Zielknoten durch.	`confirm=true` erforderlich; `nodes` müssen explizit angegeben werden
`talos_patch_config`	Wendet einen Maschinenkonfigurations-Patch an (JSON oder YAML Strategic Merge).	`dry_run` standardmäßig `true`; `confirm=true` erforderlich, wenn `dry_run=false`

Alle Tools akzeptieren ein optionales nodes-Feld (Liste von Knoten-IPs oder Hostnamen). Wenn es weggelassen wird, wird der aktive Kontext aus der talosconfig verwendet.

Sicherheitsmodell

Vertrauensgrenzen

MCP Client (Claude Code / Codex)
        │  stdio / JSON-RPC
        ▼
   talos-mcp  ◄── reads TALOSCONFIG (~/.talos/config)
        │  gRPC + mTLS
        ▼
  Talos API (each node)
        │
        ▼
    Node OS

Warnung zum Datenfluss: Tool-Antworten fließen direkt in das Kontextfenster des LLM und werden an den LLM-Anbieter gesendet. Alles, was ein Tool zurückgibt – Knoten-IPs, Hostnamen, Dienstkonfigurationen, Kernel-Protokolle, Dateiinhalte – wird Teil des Prompts, der über das Netzwerk gesendet wird. Verwenden Sie diesen Server nicht mit Clustern, die Daten enthalten, die Sie nicht an Ihren LLM-Anbieter senden möchten.

Talos RBAC wird serverseitig durchgesetzt. Die Anmeldedaten in Ihrer talosconfig bestimmen, welche Vorgänge auf jedem Knoten zulässig sind. talos-mcp kann Talos RBAC nicht umgehen – eine Anfrage, die von der API abgelehnt wird, schlägt mit einem Fehler fehl und ist nicht erfolgreich.

Tool-Klassifizierung und erforderliche RBAC-Mindestrolle

Tool	RBAC-Minimum
`talos_resource_definitions`, `talos_get`, `talos_version`, `talos_services`, `talos_containers`, `talos_processes`, `talos_health`, `talos_logs`, `talos_dmesg`, `talos_events`, `talos_list_files`, `talos_read_file`	`os:reader`
`talos_etcd`, `talos_service_action`, `talos_reboot`, `talos_upgrade`, `talos_rollback`	`os:operator`
`talos_patch_config`	`os:admin`

Sicherheitsmechanismen

Mechanismus	Funktionsweise
Nur-Lese-Modus	`TALOS_MCP_READ_ONLY=true` registriert beim Start nur Nur-Lese-Tools; mutierende Tools werden dem LLM nie zugänglich gemacht
Pfad-Allowlist	`TALOS_MCP_ALLOWED_PATHS=/etc,/proc` beschränkt `talos_read_file` und `talos_list_files` auf die angegebenen Präfixe
Bestätigungsgates	`talos_reboot`, `talos_upgrade`, `talos_rollback` und `talos_patch_config` (wenn `dry_run=false`) erfordern `confirm=true`; serverseitig durchgesetzt
Preserve-Standard	`talos_upgrade` setzt `preserve` standardmäßig auf `true` (behält EPHEMERAL-Partition bei) – unterscheidet sich vom `talosctl`-Standard `false`
Dry-Run-Standard	`talos_patch_config` ist standardmäßig auf `dry_run=true` gesetzt; das Anwenden erfordert sowohl `dry_run=false` als auch `confirm=true`
Audit-Protokollierung	Alle Aufrufe mutierender Tools (`talos_service_action`, `talos_reboot`, `talos_upgrade`, `talos_rollback`, `talos_patch_config`) geben eine strukturierte Protokollzeile an stderr aus: `AUDIT timestamp=<RFC3339> tool=<name> nodes=<list> args=<json>` (Patch-Inhalt wird geschwärzt)

Was nicht Teil des Bedrohungsmodells ist

Das LLM selbst – Prompt-Injection, halluzinierte Tool-Argumente und die Datenspeicherung des LLM-Anbieters liegen außerhalb des Zuständigkeitsbereichs dieses Servers
Der MCP-Client – die Sicherheit von Claude Code, Codex oder anderen MCP-Clients liegt in der Verantwortung dieser Projekte
Netzwerkpfad zwischen talos-mcp und Talos-Knoten – geschützt durch gegenseitiges TLS unter Verwendung der Anmeldedaten in Ihrer talosconfig

Einrichtung von Anmeldedaten mit minimalen Rechten

Erstellen Sie eine dedizierte talosconfig mit minimalen Berechtigungen für die Verwendung mit diesem Server:

Nur-Lese-Zugriff (empfohlen für die meisten Anwendungsfälle):

# Generate a reader-only talosconfig
talosctl config new --roles=os:reader talosconfig-readonly

Setzen Sie dann TALOSCONFIG=/path/to/talosconfig-readonly und TALOS_MCP_READ_ONLY=true für maximale Einschränkung. Bei dieser Einrichtung stellt der Server nur Nur-Lese-Tools bereit und die Anmeldedaten können keine mutierenden Vorgänge ausführen, selbst wenn ein Tool irgendwie umgangen würde.

Operator-Zugriff (für Dienstverwaltung, Neustart, Upgrade):

talosctl config new --roles=os:operator talosconfig-operator

Dies deckt alle Tools außer talos_patch_config ab (welches os:admin erfordert).

Vollzugriff (erforderlich für Konfigurations-Patching):

Verwenden Sie Ihre Standard-talosconfig oder generieren Sie eine mit os:admin. Reservieren Sie dies für Setups, bei denen die Konfigurations-Patch-Funktion explizit benötigt wird.

Downloads verifizieren

Prüfsummen (Integrität)

Jedes Release enthält eine talos-mcp_<version>_checksums.txt-Datei mit SHA-256-Hashes aller Archive. Überprüfen Sie die Binärdatei nach dem Herunterladen:

# Download archive and checksums
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v<version>/talos-mcp_<version>_linux_amd64.tar.gz
curl -LO https://github.com/Nosmoht/talos-mcp-server/releases/download/v<version>/talos-mcp_<version>_checksums.txt

# Verify
sha256sum --check --ignore-missing talos-mcp_<version>_checksums.txt

Dies erkennt Beschädigungen oder unvollständige Downloads. Es schützt nicht vor einer kompromittierten Release-Pipeline.

GitHub Artifact Attestations (SLSA L2-Provenienz)

Jedes Release enthält eine GitHub-native Build-Provenienz-Attestierung, die die Binärdatei kryptografisch mit dem spezifischen Commit und dem Workflow-Lauf verknüpft, der sie erstellt hat:

gh attestation verify talos-mcp_<version>_linux_amd64.tar.gz \
  --repo Nosmoht/talos-mcp-server

Dies erfordert die GitHub CLI. Eine erfolgreiche Überprüfung bedeutet, dass das Artefakt vom offiziellen Release-Workflow in diesem Repository erstellt wurde, nicht von einem Build eines Drittanbieters.

npm-Paket-Provenienz

npm-Pakete werden mit Provenienz-Attestierung veröffentlicht:

npm audit signatures

Ein erfolgreiches Ergebnis bedeutet, dass das Paket vom offiziellen GitHub Actions-Release-Workflow über OIDC Trusted Publishing veröffentlicht wurde.

Entwicklung

# Build
go build -o talos-mcp .

# Test
go test -race ./...

# Lint (requires golangci-lint v2)
golangci-lint run

# Format check
gofmt -l .

Lizenz

MIT

Talos Linux MCP Server