
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
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
--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
License
Apache-2.0
Installation
1. Install Kubeshark CLI
# macOS
brew install kubeshark
# Linux
sh Or download from [GitHub Releases](https://github.com/kubeshark/kubeshark/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"] } } }
#### 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
No common issues documented yet. If you hit a problem, the repository's GitHub Issues page is the best place to look.