Kubeshark

Kubeshark MCP Server

Kubeshark MCP (Model Context Protocol) Server ermöglicht KI-Assistenten wie Claude Desktop, Cursor und anderen MCP-kompatiblen Clients die Abfrage von Kubernetes-Netzwerkverkehr in Echtzeit.

KI-Fähigkeiten

Das MCP stellt die Werkzeuge bereit – KI-Fähigkeiten lehren Agenten, wie sie diese nutzen können. Fähigkeiten verwandeln rohe MCP-Funktionen in domänenspezifische Workflows wie Ursachenanalyse, Verkehrsfilterung und forensische Untersuchungen. Siehe die Skills-README für Installation und Nutzung.

Fähigkeit	Beschreibung
network-rca	Netzwerk-Ursachenanalyse – Snapshot-basierte retrospektive Untersuchung mit PCAP- und Dissection-Routen
kfl	KFL2-Filterexperte – Schreiben, Debuggen und Optimieren von Verkehrsabfragen über alle unterstützten Protokolle hinweg

Funktionen

• L7-API-Verkehrsanalyse: Abfrage von HTTP-, gRPC-, Redis-, Kafka-, DNS-Transaktionen
• L4-Netzwerkflüsse: Anzeige von TCP/UDP-Flüssen mit Verkehrsstatistiken
• Cluster-Verwaltung: Starten/Stoppen von Kubeshark-Bereitstellungen (mit Sicherheitskontrollen)
• PCAP-Snapshots: Erstellen und Exportieren von Netzwerkmitschnitten
• Eingebaute Prompts: Vorkonfigurierte Prompts für häufige Analyseaufgaben

Installation

1. Kubeshark CLI installieren

# macOS
brew install kubeshark

# Linux
sh <(curl -Ls https://kubeshark.com/install)

# Windows (PowerShell)
choco install kubeshark

Oder laden Sie es von GitHub Releases herunter.

2. Claude Desktop konfigurieren

Fügen Sie es zu Ihrer Claude Desktop-Konfiguration hinzu:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Standard (erfordert kubectl-Zugriff / Kube-Kontext)

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp"]
    }
  }
}

Mit explizitem Kubeconfig-Pfad:

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--kubeconfig", "/path/to/.kube/config"]
    }
  }
}

URL-Modus (kein kubectl erforderlich)

Verwenden Sie dies, wenn die Maschine keinen kubectl-Zugriff oder Kube-Kontext hat. Verbinden Sie sich direkt mit einer bestehenden Kubeshark-Bereitstellung:

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--url", "https://kubeshark.example.com"]
    }
  }
}

Für einen abgeschotteten Hub (AUTH_ENABLED=true) kann der URL-Modus kein Token ausstellen (kein Kube-Zugriff), geben Sie daher explizit eines über --token (oder die Umgebungsvariable KUBESHARK_HUB_TOKEN) an. Stellen Sie es von einer Maschine mit Cluster-Zugriff aus:

kubectl create token kubeshark-cli -n <release-namespace> --audience kubeshark-hub

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--url", "https://kubeshark.example.com", "--token", "<token>"]
    }
  }
}

Das Token ist kurzlebig (~1h) und der URL-Modus kann es nicht automatisch erneuern; wenn es abläuft, meldet der Server eine klare 401 ... token expired/invalid-Meldung – stellen Sie es erneut aus und starten Sie neu. Der Proxy-Modus (Standard, mit Kube-Zugriff) stellt das kubeshark-cli-Token automatisch aus und erneuert es automatisch, sodass langlebige Sitzungen nicht ablaufen.

Mit destruktiven Operationen

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--allow-destructive", "--kubeconfig", "/path/to/.kube/config"]
    }
  }
}

3. Konfiguration generieren

Verwenden Sie die CLI, um die Konfiguration zu generieren:

kubeshark mcp --mcp-config --url https://kubeshark.example.com

Verfügbare Werkzeuge

Verkehrsanalyse (Alle Modi)

Werkzeug	Beschreibung
list_workloads	Pods, Services, Namespaces mit beobachtetem Verkehr auflisten
list_api_calls	L7-API-Transaktionen mit KFL-Filterung abfragen
get_api_call	Detaillierte Informationen zu einem bestimmten API-Aufruf abrufen
get_api_stats	Aggregierte API-Statistiken abrufen
list_l4_flows	L4 (TCP/UDP) Netzwerkflüsse auflisten
get_l4_flow_summary	L4-Konnektivitätszusammenfassung abrufen
list_snapshots	Alle PCAP-Snapshots auflisten
create_snapshot	Einen neuen PCAP-Snapshot erstellen
get_dissection_status	L7-Protokoll-Parsing-Status prüfen
enable_dissection	L7-Protokoll-Dissection aktivieren
disable_dissection	L7-Protokoll-Dissection deaktivieren

Cluster-Verwaltung (Nur Proxy-Modus)

Werkzeug	Beschreibung	Erfordert
check_kubeshark_status	Prüfen, ob Kubeshark läuft	-
start_kubeshark	Kubeshark im Cluster bereitstellen	--allow-destructive
stop_kubeshark	Kubeshark aus dem Cluster entfernen	--allow-destructive

Verfügbare Prompts

Prompt	Beschreibung
analyze_traffic	API-Verkehrsmuster analysieren und Probleme identifizieren
find_errors	API-Fehler und -Ausfälle finden und zusammenfassen
trace_request	Einen Anfragepfad durch Microservices verfolgen
show_topology	Service-Kommunikationstopologie anzeigen
latency_analysis	Latenzmuster analysieren und langsame Endpunkte identifizieren
security_audit	Verkehr auf Sicherheitsbedenken prüfen
compare_traffic	Verkehrsmuster zwischen Zeiträumen vergleichen
debug_connection	Konnektivitätsprobleme zwischen Services debuggen

Beispielkonversationen

User: Show me all HTTP 500 errors in the last hour

Claude: I'll query the API traffic for 500 errors.
[Calling list_api_calls with kfl="http and response.status == 500"]

Found 12 HTTP 500 errors:
1. POST /api/checkout -> payment-service (500)
   Time: 10:23:45 | Latency: 2340ms
...

User: What services are communicating with the database?

Claude: Let me check the L4 flows to the database.
[Calling list_l4_flows with dst_filter="postgres"]

Found 5 services connecting to postgres:5432:
- orders-service: 456KB transferred
- users-service: 123KB transferred
...

CLI-Optionen

Option	Beschreibung
--url	Direkte URL zum Kubeshark Hub
--token	Hub-SA/Bearer-Token für den --url-Modus gegen einen abgeschotteten Hub (auch KUBESHARK_HUB_TOKEN); ignoriert im Proxy-Modus, der das Token ausstellt und automatisch erneuert
--kubeconfig	Pfad zur Kubeconfig-Datei
--allow-destructive	Start/Stopp-Operationen aktivieren
--list-tools	Verfügbare Werkzeuge auflisten und beenden
--mcp-config	Claude Desktop-Konfigurations-JSON ausgeben

KFL (Kubeshark Filter Language)

Verkehr mit KFL-Syntax abfragen:

# HTTP requests to a specific path
http and request.path == "/api/users"

# Errors only
response.status >= 400

# Specific source pod
src.pod.name == "frontend-.*"

# Multiple conditions
http and src.namespace == "default" and response.status == 500

MCP-Registry

Kubeshark wird bei jedem Release automatisch in der MCP-Registry veröffentlicht.

Die server.json in diesem Verzeichnis ist eine Referenzdatei. Die eigentlichen Registry-Metadaten (Version, SHA256-Hashes) werden während des Release-Workflows automatisch generiert. Siehe .github/workflows/release.yml für Details.

Links

• Dokumentation
• GitHub
• Website
• MCP-Registry

Lizenz

Apache-2.0