Kubeshark

Kubeshark MCP Server

Kubeshark MCP (Model Context Protocol) server enables AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to query real-time Kubernetes network traffic.

AI Skills

The MCP provides the tools — AI skills teach agents how to use them. Skills turn raw MCP capabilities into domain-specific workflows like root cause analysis, traffic filtering, and forensic investigation. See the skills README for installation and usage.

Skill	Description
network-rca	Network Root Cause Analysis — snapshot-based retrospective investigation with PCAP and dissection routes
kfl	KFL2 filter expert — write, debug, and optimize traffic queries across all supported protocols

Features

• L7 API Traffic Analysis: Query HTTP, gRPC, Redis, Kafka, DNS transactions
• L4 Network Flows: View TCP/UDP flows with traffic statistics
• Cluster Management: Start/stop Kubeshark deployments (with safety controls)
• PCAP Snapshots: Create and export network captures
• Built-in Prompts: Pre-configured prompts for common analysis tasks

Installation

1. Install Kubeshark CLI

# macOS
brew install kubeshark

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

# Windows (PowerShell)
choco install kubeshark

Or download from GitHub Releases.

2. Configure Claude Desktop

Add to your Claude Desktop configuration:

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

Default (requires kubectl access / kube context)

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

With an explicit kubeconfig path:

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

URL Mode (no kubectl required)

Use this when the machine doesn't have kubectl access or a kube context. Connect directly to an existing Kubeshark deployment:

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

For a gated Hub (AUTH_ENABLED=true), URL mode can't mint a token (no kube access), so supply one explicitly via --token (or the KUBESHARK_HUB_TOKEN env var). Mint it from a machine that has cluster access:

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

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

The token is short-lived (~1h) and URL mode cannot auto-renew it; when it expires the server reports a clear 401 ... token expired/invalid message — re-mint and restart. Proxy mode (default, with kube access) mints the kubeshark-cli token automatically and auto-renews it, so long-running sessions don't expire.

With Destructive Operations

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

3. Generate Configuration

Use the CLI to generate configuration:

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

Available Tools

Traffic Analysis (All Modes)

Tool	Description
list_workloads	List pods, services, namespaces with observed traffic
list_api_calls	Query L7 API transactions with KFL filtering
get_api_call	Get detailed info about a specific API call
get_api_stats	Get aggregated API statistics
list_l4_flows	List L4 (TCP/UDP) network flows
get_l4_flow_summary	Get L4 connectivity summary
list_snapshots	List all PCAP snapshots
create_snapshot	Create a new PCAP snapshot
get_dissection_status	Check L7 protocol parsing status
enable_dissection	Enable L7 protocol dissection
disable_dissection	Disable L7 protocol dissection

Cluster Management (Proxy Mode Only)

Tool	Description	Requires
check_kubeshark_status	Check if Kubeshark is running	-
start_kubeshark	Deploy Kubeshark to cluster	--allow-destructive
stop_kubeshark	Remove Kubeshark from cluster	--allow-destructive

Available Prompts

Prompt	Description
analyze_traffic	Analyze API traffic patterns and identify issues
find_errors	Find and summarize API errors and failures
trace_request	Trace a request path through microservices
show_topology	Show service communication topology
latency_analysis	Analyze latency patterns and identify slow endpoints
security_audit	Audit traffic for security concerns
compare_traffic	Compare traffic patterns between time periods
debug_connection	Debug connectivity issues between services

Example Conversations

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 Options

Option	Description
--url	Direct URL to Kubeshark Hub
--token	Hub SA/bearer token for --url mode against a gated Hub (also KUBESHARK_HUB_TOKEN); ignored in proxy mode, which mints and auto-renews the token
--kubeconfig	Path to kubeconfig file
--allow-destructive	Enable start/stop operations
--list-tools	List available tools and exit
--mcp-config	Print Claude Desktop config JSON

KFL (Kubeshark Filter Language)

Query traffic using KFL syntax:

# 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 is published to the MCP Registry automatically on each release.

The server.json in this directory is a reference file. The actual registry metadata (version, SHA256 hashes) is auto-generated during the release workflow. See .github/workflows/release.yml for details.

Links

• Documentation
• GitHub
• Website
• MCP Registry

License

Apache-2.0