ContextQMD
Back to Kubeshark

Kubeshark MCP Server

mcp/README.md

72.3.836.2 KB
Original Source

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.

SkillDescription
network-rcaNetwork Root Cause Analysis — snapshot-based retrospective investigation with PCAP and dissection routes
kflKFL2 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

bash
# 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)

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

With an explicit kubeconfig path:

json
{
  "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:

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

With Destructive Operations

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

3. Generate Configuration

Use the CLI to generate configuration:

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

Available Tools

Traffic Analysis (All Modes)

ToolDescription
list_workloadsList pods, services, namespaces with observed traffic
list_api_callsQuery L7 API transactions with KFL filtering
get_api_callGet detailed info about a specific API call
get_api_statsGet aggregated API statistics
list_l4_flowsList L4 (TCP/UDP) network flows
get_l4_flow_summaryGet L4 connectivity summary
list_snapshotsList all PCAP snapshots
create_snapshotCreate a new PCAP snapshot
get_dissection_statusCheck L7 protocol parsing status
enable_dissectionEnable L7 protocol dissection
disable_dissectionDisable L7 protocol dissection

Cluster Management (Proxy Mode Only)

ToolDescriptionRequires
check_kubeshark_statusCheck if Kubeshark is running-
start_kubesharkDeploy Kubeshark to cluster--allow-destructive
stop_kubesharkRemove Kubeshark from cluster--allow-destructive

Available Prompts

PromptDescription
analyze_trafficAnalyze API traffic patterns and identify issues
find_errorsFind and summarize API errors and failures
trace_requestTrace a request path through microservices
show_topologyShow service communication topology
latency_analysisAnalyze latency patterns and identify slow endpoints
security_auditAudit traffic for security concerns
compare_trafficCompare traffic patterns between time periods
debug_connectionDebug 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

OptionDescription
--urlDirect URL to Kubeshark Hub
--kubeconfigPath to kubeconfig file
--allow-destructiveEnable start/stop operations
--list-toolsList available tools and exit
--mcp-configPrint 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.

License

Apache-2.0