Kubeshark MCP Server

oficial

Acesso MCP ao tráfego de rede L4 e L7 em todo o cluster, pacotes, APIs e payloads completos.

Documentação

Servidor MCP Kubeshark

O servidor MCP (Model Context Protocol) do Kubeshark permite que assistentes de IA como Claude Desktop, Cursor e outros clientes compatíveis com MCP consultem tráfego de rede Kubernetes em tempo real.

Habilidades de IA

O MCP fornece as ferramentas — as habilidades de IA ensinam os agentes a usá-las. As habilidades transformam capacidades brutas do MCP em fluxos de trabalho específicos de domínio, como análise de causa raiz, filtragem de tráfego e investigação forense. Consulte o README de habilidades para instalação e uso.

Habilidade	Descrição
`network-rca`	Análise de Causa Raiz de Rede — investigação retrospectiva baseada em snapshot com rotas PCAP e de dissecação
`kfl`	Especialista em filtros KFL2 — escreva, depure e otimize consultas de tráfego em todos os protocolos suportados

Funcionalidades

Análise de Tráfego de API L7: Consultar transações HTTP, gRPC, Redis, Kafka, DNS
Fluxos de Rede L4: Visualizar fluxos TCP/UDP com estatísticas de tráfego
Gerenciamento de Cluster: Iniciar/parar implantações do Kubeshark (com controles de segurança)
Snapshots PCAP: Criar e exportar capturas de rede
Prompts Integrados: Prompts pré-configurados para tarefas comuns de análise

Instalação

1. Instalar a CLI do Kubeshark

# macOS
brew install kubeshark

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

# Windows (PowerShell)
choco install kubeshark

Ou baixe de GitHub Releases.

2. Configurar o Claude Desktop

Adicione à configuração do Claude Desktop:

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

Padrão (requer acesso kubectl / contexto kube)

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

Com um caminho de kubeconfig explícito:

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

Modo URL (sem necessidade de kubectl)

Use quando a máquina não tiver acesso kubectl ou um contexto kube. Conecte-se diretamente a uma implantação existente do Kubeshark:

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

Com Operações Destrutivas

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

3. Gerar Configuração

Use a CLI para gerar a configuração:

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

Ferramentas Disponíveis

Análise de Tráfego (Todos os Modos)

Ferramenta	Descrição
`list_workloads`	Listar pods, serviços, namespaces com tráfego observado
`list_api_calls`	Consultar transações de API L7 com filtragem KFL
`get_api_call`	Obter informações detalhadas sobre uma chamada de API específica
`get_api_stats`	Obter estatísticas agregadas de API
`list_l4_flows`	Listar fluxos de rede L4 (TCP/UDP)
`get_l4_flow_summary`	Obter resumo de conectividade L4
`list_snapshots`	Listar todos os snapshots PCAP
`create_snapshot`	Criar um novo snapshot PCAP
`get_dissection_status`	Verificar status de análise de protocolo L7
`enable_dissection`	Habilitar dissecação de protocolo L7
`disable_dissection`	Desabilitar dissecação de protocolo L7

Gerenciamento de Cluster (Apenas Modo Proxy)

Ferramenta	Descrição	Requer
`check_kubeshark_status`	Verificar se o Kubeshark está em execução	-
`start_kubeshark`	Implantar Kubeshark no cluster	`--allow-destructive`
`stop_kubeshark`	Remover Kubeshark do cluster	`--allow-destructive`

Prompts Disponíveis

Prompt	Descrição
`analyze_traffic`	Analisar padrões de tráfego de API e identificar problemas
`find_errors`	Encontrar e resumir erros e falhas de API
`trace_request`	Rastrear o caminho de uma requisição através de microsserviços
`show_topology`	Mostrar topologia de comunicação entre serviços
`latency_analysis`	Analisar padrões de latência e identificar endpoints lentos
`security_audit`	Auditar tráfego em busca de preocupações de segurança
`compare_traffic`	Comparar padrões de tráfego entre períodos de tempo
`debug_connection`	Depurar problemas de conectividade entre serviços

Exemplos de Conversas

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
...

Opções da CLI

Opção	Descrição
`--url`	URL direta para o Kubeshark Hub
`--kubeconfig`	Caminho para o arquivo kubeconfig
`--allow-destructive`	Habilitar operações de iniciar/parar
`--list-tools`	Listar ferramentas disponíveis e sair
`--mcp-config`	Imprimir JSON de configuração do Claude Desktop

KFL (Kubeshark Filter Language)

Consultar tráfego usando sintaxe KFL:

# 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

Registro MCP

O Kubeshark é publicado no Registro MCP automaticamente a cada lançamento.

O server.json neste diretório é um arquivo de referência. Os metadados reais do registro (versão, hashes SHA256) são gerados automaticamente durante o fluxo de trabalho de lançamento. Consulte .github/workflows/release.yml para detalhes.

Licença

Apache-2.0