list_workloadsLABSCO SUMMARY
Cluster traffic as something you can query, with a filter language instead of tcpdump and a terminal.
KFL carries the weight: a filter like http and response.status == 500 narrows a live capture to the failures worth reading, and the same syntax covers HTTP, gRPC, Redis, Kafka and DNS. The reading tools work in either mode, while starting and stopping Kubeshark itself sits behind --allow-destructive — so an agent connected with the defaults cannot change what is deployed in the cluster.
What it is
The MCP server built into the Kubeshark CLI. It queries a Kubeshark deployment's real-time capture of cluster traffic: L7 API transactions, L4 flows, and PCAP snapshots.
What you get
- Pods, services and namespaces that have traffic against them — list_workloads
- L7 API transactions filtered in KFL, Kubeshark's query language, and the full detail of any single call — list_api_calls, get_api_call
- Aggregated API statistics rather than individual calls — get_api_stats
- TCP and UDP flows, and a connectivity summary over them — list_l4_flows, get_l4_flow_summary
- PCAP snapshots created and listed, for going back over something after it happened — create_snapshot, list_snapshots
- L7 protocol dissection checked, switched on and switched off — get_dissection_status, enable_dissection, disable_dissection
- Whether Kubeshark is running in the cluster, and — only with --allow-destructive — deploying or removing it — check_kubeshark_status, start_kubeshark, stop_kubeshark
- Prompts for the investigations people actually run: analyze_traffic, find_errors, trace_request, show_topology, latency_analysis, security_audit, compare_traffic, debug_connection
Requirements
The Kubeshark CLI on the machine — brew, the install script, or choco — launched as kubeshark mcp. By default it goes through your kube context, takes --kubeconfig for an explicit path, and mints and auto-renews its own kubeshark-cli token. Where there is no kubectl access, --url points straight at a Kubeshark Hub; against a gated Hub you supply the token yourself with --token or KUBESHARK_HUB_TOKEN, and since URL mode cannot renew it, that short-lived token — about an hour — expires into a 401 and has to be re-minted. Deploying or removing Kubeshark needs --allow-destructive.
Setup effort
One command — brew install kubeshark
USE CASES
01
Finding out which requests are failing right now
Filter the live API traffic down to the error responses, then open one call to see the request that produced it.
02
Working out what is talking to what
List the workloads with observed traffic, then read the L4 connectivity summary between them.
03
Chasing a slow endpoint
Pull aggregated statistics first to see where the latency sits, then the individual calls behind it.
04
Investigating something after it has stopped happening
Take a PCAP snapshot while it is still in the capture window, then work from the snapshot list.
05
Getting a protocol parsed that is coming back as raw bytes
Check whether dissection is on for it, and switch it on for the investigation.
06
Checking whether there is anything capturing at all
Ask whether Kubeshark is running in the cluster before reading traffic that may not exist.
14 tools
Listed in project docs. Your client may show a different list.
list_api_callsget_api_callget_api_statslist_l4_flowsget_l4_flow_summarylist_snapshotscreate_snapshotget_dissection_statusenable_dissectiondisable_dissectioncheck_kubeshark_statusstart_kubesharkstop_kubesharkBEFORE YOU INSTALL
What to know first
Tools you get
14 tools named in the project's documentation.
Requires
- The Kubeshark CLI on PATH (brew install kubeshark, the Linux install script, or choco install kubeshark)
- Kubeshark installed in your cluster
- kubectl access through your kube context — or, in URL mode, a Kubeshark Hub address and, for a gated Hub, a token
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
brew install kubesharkMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"kubeshark": {
"command": "kubeshark",
"args": [
"mcp"
]
}
}
}The configuration above runs in proxy mode through your kube context, which mints and renews the Hub token itself. KUBESHARK_HUB_TOKEN is only for URL mode against a gated Hub: add "--url", your Hub address, "--token" and the token to args, or set KUBESHARK_HUB_TOKEN in the server's environment. Mint the token on a machine with cluster access with kubectl create token kubeshark-cli -n <release-namespace> --audience kubeshark-hub; it lasts about an hour and URL mode cannot renew it.
