MCP CLI

Coming Soon — V2.00: MCP integration is coming as part of Kubeshark V2.00. Read the announcement.

The kubeshark mcp command runs an MCP (Model Context Protocol) server over stdio, enabling AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to query Kubeshark’s network visibility data.

Quick Start

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

This starts an MCP server that communicates over stdin/stdout using the MCP protocol, connecting to an existing Kubeshark deployment.

To see available tools:

kubeshark mcp --list-tools --url https://kubeshark.example.com

Configuration for Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

URL Mode (Recommended)

Connect directly to an existing Kubeshark deployment:

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

In URL mode:

Connects directly to the Kubeshark Hub
No kubectl or kubeconfig required
Cluster management tools (start/stop) are disabled
All traffic analysis tools work normally

Proxy Mode

When no --url is provided, the MCP CLI will:

Proxy into the cluster using kubectl port-forward
Connect to deployed Kubeshark if it’s running
All traffic analysis tools work normally

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

By default, proxy mode operates in read-only mode. To enable AI assistants to start or stop Kubeshark, add --allow-destructive:

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

CLI Options

Option	Description
`--url`	Connect directly to Kubeshark URL (disables cluster management)
`--kubeconfig`	Path to kubeconfig file for proxy mode
`--allow-destructive`	Enable destructive operations (`start_kubeshark`, `stop_kubeshark`)
`--list-tools`	List available MCP tools and exit
`--mcp-config`	Print MCP client configuration JSON and exit

Generate Configuration

To generate the Claude Desktop configuration automatically:

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

Output:

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

Examples

# List available tools from a Kubeshark instance
kubeshark mcp --list-tools --url https://kubeshark.example.com

# Use specific kubeconfig (proxy mode)
kubeshark mcp --kubeconfig ~/.kube/config

# Enable destructive operations (proxy mode)
kubeshark mcp --allow-destructive --kubeconfig ~/.kube/config

# Connect to local port-forwarded instance
kubeshark mcp --url http://localhost:8899

Available Tools

The MCP server exposes tools dynamically from the Kubeshark Hub. Use --list-tools to see all available tools.

Traffic Analysis Tools

These tools are fetched from the Hub and work in both URL and proxy modes:

Tool	Description
`list_workloads`	List pods, services, namespaces with observed traffic
`list_api_calls`	Query L7 API transactions (HTTP, gRPC, Redis, Kafka, DNS)
`get_api_call`	Get detailed information about a specific API call
`get_api_stats`	Get aggregated API statistics
`list_l4_flows`	List L4 (TCP/UDP) network flows with traffic stats
`get_l4_flow_summary`	Get L4 connectivity summary (top talkers, cross-ns traffic)
`get_dissection_status`	Check L7 protocol parsing status
`enable_dissection`	Enable L7 protocol dissection
`disable_dissection`	Disable L7 protocol dissection
`list_snapshots`	List all PCAP snapshots
`create_snapshot`	Create a new PCAP snapshot
`get_snapshot`	Get snapshot details
`delete_snapshot`	Delete a snapshot
`export_snapshot_pcap`	Export snapshot as PCAP file

Cluster Management Tools (Proxy Mode Only)

These tools are only available in proxy mode (without --url):

Tool	Description	Requires
`check_kubeshark_status`	Check if Kubeshark is running (read-only)	-
`start_kubeshark`	Deploy Kubeshark to the cluster	`--allow-destructive`
`stop_kubeshark`	Remove Kubeshark from the cluster	`--allow-destructive`

Prompts

The MCP server also provides pre-built prompts for common analysis tasks:

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

Tool Details

`check_kubeshark_status`

Checks if Kubeshark is running in the cluster. Safe, read-only operation.

Parameters:

Parameter	Type	Description
`release_namespace`	string	Namespace where Kubeshark is installed (default: “default”)

`start_kubeshark`

Deploys Kubeshark to the cluster. Requires --allow-destructive flag.

Parameters:

Parameter	Type	Description
`namespaces`	string	Comma-separated namespaces to tap (e.g., “default,sock-shop”)
`pod_regex`	string	Regular expression to filter pods (e.g., “frontend.*“)
`release_namespace`	string	Namespace where Kubeshark will be installed

Example:

{
  "namespaces": "default,sock-shop",
  "pod_regex": "frontend.*"
}

`stop_kubeshark`

Removes Kubeshark from the cluster. Requires --allow-destructive flag.

Parameters:

Parameter	Type	Description
`release_namespace`	string	Namespace where Kubeshark is installed

Example Conversation

+---------------------------------------------------------------------------------+
| Claude Desktop                                                                  |
+---------------------------------------------------------------------------------+
|                                                                                 |
|  User: Show me the L4 network flows in my cluster                               |
|                                                                                 |
|  Claude: I'll query the L4 flows.                                               |
|                                                                                 |
|  [Calling list_l4_flows]                                                        |
|                                                                                 |
|  Here are the active L4 flows:                                                  |
|                                                                                 |
|  1. frontend-pod -> orders-service:8080 (TCP)                                   |
|     Bytes: 1.2MB | Packets: 8,432 | RTT: 2.3ms                                  |
|                                                                                 |
|  2. orders-service -> postgres:5432 (TCP)                                       |
|     Bytes: 456KB | Packets: 3,211 | RTT: 0.8ms                                  |
|                                                                                 |
|  User: Show me 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                                            |
|                                                                                 |
|  The payment-service is responsible for 8 of the 12 errors.                     |
|                                                                                 |
+---------------------------------------------------------------------------------+

Troubleshooting

Cannot connect to Kubeshark URL

Verify the URL is accessible: curl https://kubeshark.example.com/api/mcp
Check for authentication requirements
Ensure the Kubeshark Hub has MCP enabled

Cannot connect to cluster (proxy mode)

Verify kubectl works: kubectl get nodes
Check your kubeconfig: kubectl config current-context
Try specifying the kubeconfig explicitly: kubeshark mcp --kubeconfig ~/.kube/config

Cluster management tools disabled

In --url mode: Cluster management tools are always disabled
In proxy mode without --allow-destructive: Only check_kubeshark_status is available
Add --allow-destructive to enable start_kubeshark and stop_kubeshark

MCP server not responding

Test with --list-tools: kubeshark mcp --list-tools --url <your-url>
Check that Kubeshark Hub is running and accessible
Check Claude Desktop logs for errors

What’s Next

How MCP Works — Understanding the Model Context Protocol
L7 Tools Reference — L7 API traffic analysis tools
L4 Tools Reference — L4 network flow tools
Use Cases — What you can do with MCP