kubectl-mcp

Ein MCP (Model Context Protocol)-Server, der es KI-Agenten ermöglicht, Kubernetes-Cluster in einfachem Englisch zu untersuchen – fragen Sie „Welche Pods wurden in der letzten Stunde neu gestartet?" und erhalten Sie eine echte Antwort.

Erstellt von Teresa Tran.

Warum

LLM-Assistenten sind großartig darin, kubectl-Befehle zu erklären, und schrecklich darin, sie tatsächlich sicher auszuführen. kubectl-mcp stellt schreibgeschützte Cluster-Inspektion als eine Reihe von MCP-Tools bereit, die ein Agent aufrufen kann – und verwandelt „Prüfe meinen Cluster" von Copy-Paste-und-Hoffen in ein echtes Gespräch.

• Von Natur aus schreibgeschützt. Kein apply, kein delete, kein exec. Der Server untersucht nur.

• Standardmäßig im Mock-Modus. Wird mit einem vorbefüllten Fake-Cluster geliefert, sodass Sie es in 30 Sekunden ohne echten Cluster ausprobieren können.

• Echter Modus, wenn Sie bereit sind. Richten Sie es auf Ihre KUBECONFIG aus und es fragt einen Live-Cluster über den offiziellen Kubernetes-Python-Client ab.

Related MCP server: mcp-k8s-context-server

Installation

pip install kubectl-mcp                # mock mode (default)
pip install "kubectl-mcp[real]"        # + real-cluster support (kubernetes client)

Oder aus dem Quellcode:

git clone https://github.com/teresa-tran/kubectl-mcp.git
cd kubectl-mcp
pip install -e ".[real,dev]"

Eigenständig ausführen (Sanity-Check)

kubectl-mcp --help                     # show flags
kubectl-mcp --list-tools               # print every MCP tool + its schema
kubectl-mcp --demo list_pods           # run a tool once against the mock cluster
kubectl-mcp --demo find_restarted_pods --arg since_minutes=120

In einen MCP-Client einbinden

Claude Desktop

Fügen Sie zu ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) hinzu:

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp"
    }
  }
}

Für den echten Cluster-Modus:

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp",
      "env": {
        "KUBECTL_MCP_MODE": "real",
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Starten Sie Claude Desktop neu. Sie sollten nun in der Lage sein, „Liste die Pods im Produktions-Namespace auf" zu fragen und eine echte Antwort zu erhalten.

Andere MCP-kompatible Clients

Jeder Client, der stdio-MCP spricht (Cursor, Cline, Continue, benutzerdefinierte Agenten), funktioniert auf die gleiche Weise – richten Sie ihn auf die kubectl-mcp-Binärdatei aus.

Verfügbare Tools

Jedes Tool hat ein JSON-Schema – LLMs erhalten automatisch eine ordnungsgemäße Argumentvalidierung.

Konfiguration

Umgebungsvariablen:

Der Mock-Cluster

Der standardmäßige Mock-Cluster befindet sich in src/kubectl_mcp/mock_data.json und enthält:

• 3 Namespaces: default, production, staging

• ~15 Pods, die gesunde, abstürzende und kürzlich neu gestartete Zustände abdecken

• Deployments, Dienste und einen Strom aktueller Ereignisse

• Einige Pods haben Neustartanzahlen > 0, sodass find_restarted_pods echte Ergebnisse liefert

Sie können es überschreiben, indem Sie KUBECTL_MCP_MOCK_DATA=/pfad/zu/ihrer.json setzen, wenn Sie ein bestimmtes Szenario demonstrieren möchten.

Designhinweise

• Von Natur aus schreibgeschützt. Das KubernetesBackend-Protokoll definiert nur Lesemethoden. Es gibt keinen Codepfad, der den Clusterzustand verändern kann – selbst im echten Modus.

• Backend ist austauschbar. MockBackend und RealBackend implementieren dasselbe Protokoll. Das Hinzufügen eines dritten (z. B. eines zwischengespeicherten Snapshots) ist eine Datei.

• Fehler sind Ausnahmen, keine stillen Nullen. ResourceNotFound, NamespaceNotFound usw. werden als McpError mit hilfreichen Meldungen weitergegeben, damit der Agent korrigieren kann.

• stdio-Transport. Alle MCP-Toolaufrufe sind JSON-RPC über stdio, genau gemäß der MCP-Spezifikation.

Entwicklung

pip install -e ".[real,dev]"
pytest                                 # run tests
ruff check src tests                   # lint
kubectl-mcp --demo list_pods --arg namespace=production   # smoke test

Roadmap

• Mock-Backend mit vorbefüllten Daten

• Echtes Backend über den kubernetes-Python-Client

• Schreibgeschützte Tool-Oberfläche

• Eigenständiger --demo-Modus für CI/Smoke-Tests

• Multi-Cluster-Unterstützung (--context-Flag)

• Metrik-Tools (CPU/Speicher über metrics.k8s.io)

• Optionale Caching-Schicht für häufige Abfragen

Lizenz

MIT © 2026 Teresa Tran