Kubeshark

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 o tráfego de rede do 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 de PCAP e 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 à sua 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 ao 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"]
    }
  }
}

Para um Hub protegido (AUTH_ENABLED=true), o modo URL não pode gerar um token (sem acesso ao kube), então forneça um explicitamente via --token (ou a variável de ambiente KUBESHARK_HUB_TOKEN). Gere-o a partir de uma máquina que tenha acesso ao cluster:

kubectl create token kubeshark-cli -n <release-namespace> --audience kubeshark-hub

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

O token tem vida curta (~1h) e o modo URL não pode renová-lo automaticamente; quando expirar, o servidor reporta uma mensagem clara 401 ... token expired/invalid — gere novamente e reinicie. O modo proxy (padrão, com acesso ao kube) gera o token kubeshark-cli automaticamente e renova automaticamente, para que sessões de longa duração não expirem.

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 o status de análise de protocolo L7
enable_dissection	Habilitar a dissecação de protocolo L7
disable_dissection	Desabilitar a 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 o Kubeshark no cluster	--allow-destructive
stop_kubeshark	Remover o 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 dos microsserviços
show_topology	Mostrar a topologia de comunicação entre serviços
latency_analysis	Analisar padrões de latência e identificar endpoints lentos
security_audit	Auditar o 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 Hub do Kubeshark
--token	Token SA/bearer do Hub para o modo --url contra um Hub protegido (também KUBESHARK_HUB_TOKEN); ignorado no modo proxy, que gera e renova automaticamente o token
--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 (Linguagem de Filtro do Kubeshark)

Consultar tráfego usando a 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.

Links

• Documentação
• GitHub
• Website
• Registro MCP

Licença

Apache-2.0