Kubeshark

Servidor MCP de Kubeshark

Kubeshark MCP (Protocolo de Contexto de Modelo) permite que asistentes de IA como Claude Desktop, Cursor y otros clientes compatibles con MCP consulten tráfico de red de Kubernetes en tiempo real.

Habilidades de IA

El MCP proporciona las herramientas — las habilidades de IA enseñan a los agentes cómo usarlas. Las habilidades convierten las capacidades MCP en bruto en flujos de trabajo específicos del dominio, como análisis de causa raíz, filtrado de tráfico e investigación forense. Consulte el README de habilidades para instalación y uso.

Habilidad	Descripción
network-rca	Análisis de Causa Raíz de Red — investigación retrospectiva basada en instantáneas con rutas de PCAP y disección
kfl	Experto en filtros KFL2 — escribir, depurar y optimizar consultas de tráfico en todos los protocolos soportados

Características

• Análisis de Tráfico de API L7: Consultar transacciones HTTP, gRPC, Redis, Kafka, DNS
• Flujos de Red L4: Ver flujos TCP/UDP con estadísticas de tráfico
• Gestión de Clúster: Iniciar/detener despliegues de Kubeshark (con controles de seguridad)
• Instantáneas PCAP: Crear y exportar capturas de red
• Prompts Integrados: Prompts preconfigurados para tareas de análisis comunes

Instalación

1. Instalar la CLI de Kubeshark

# macOS
brew install kubeshark

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

# Windows (PowerShell)
choco install kubeshark

O descargar desde GitHub Releases.

2. Configurar Claude Desktop

Añadir a su configuración de Claude Desktop:

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

Predeterminado (requiere acceso a kubectl / contexto de kube)

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

Con una ruta de kubeconfig explícita:

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

Modo URL (no requiere kubectl)

Úselo cuando la máquina no tenga acceso a kubectl o un contexto de kube. Conéctese directamente a un despliegue existente de Kubeshark:

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

Para un Hub protegido (AUTH_ENABLED=true), el modo URL no puede generar un token (sin acceso a kube), así que proporcione uno explícitamente mediante --token (o la variable de entorno KUBESHARK_HUB_TOKEN). Genérelo desde una máquina que tenga acceso al clúster:

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

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

El token es de corta duración (~1h) y el modo URL no puede renovarlo automáticamente; cuando expira, el servidor informa un mensaje claro 401 ... token expired/invalid — regenere y reinicie. El modo proxy (predeterminado, con acceso a kube) genera el token kubeshark-cli automáticamente y lo renueva automáticamente, por lo que las sesiones de larga duración no expiran.

Con Operaciones Destructivas

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

3. Generar Configuración

Use la CLI para generar la configuración:

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

Herramientas Disponibles

Análisis de Tráfico (Todos los Modos)

Herramienta	Descripción
list_workloads	Listar pods, servicios, namespaces con tráfico observado
list_api_calls	Consultar transacciones de API L7 con filtrado KFL
get_api_call	Obtener información detallada sobre una llamada API específica
get_api_stats	Obtener estadísticas agregadas de API
list_l4_flows	Listar flujos de red L4 (TCP/UDP)
get_l4_flow_summary	Obtener resumen de conectividad L4
list_snapshots	Listar todas las instantáneas PCAP
create_snapshot	Crear una nueva instantánea PCAP
get_dissection_status	Verificar el estado de análisis de protocolo L7
enable_dissection	Habilitar la disección de protocolo L7
disable_dissection	Deshabilitar la disección de protocolo L7

Gestión de Clúster (Solo Modo Proxy)

Herramienta	Descripción	Requiere
check_kubeshark_status	Verificar si Kubeshark está en ejecución	-
start_kubeshark	Desplegar Kubeshark en el clúster	--allow-destructive
stop_kubeshark	Eliminar Kubeshark del clúster	--allow-destructive

Prompts Disponibles

Prompt	Descripción
analyze_traffic	Analizar patrones de tráfico de API e identificar problemas
find_errors	Encontrar y resumir errores y fallos de API
trace_request	Rastrear la ruta de una solicitud a través de microservicios
show_topology	Mostrar la topología de comunicación entre servicios
latency_analysis	Analizar patrones de latencia e identificar endpoints lentos
security_audit	Auditar el tráfico en busca de problemas de seguridad
compare_traffic	Comparar patrones de tráfico entre períodos de tiempo
debug_connection	Depurar problemas de conectividad entre servicios

Conversaciones de Ejemplo

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

Opciones de CLI

Opción	Descripción
--url	URL directa al Hub de Kubeshark
--token	Token SA/bearer del Hub para el modo --url contra un Hub protegido (también KUBESHARK_HUB_TOKEN); ignorado en modo proxy, que genera y renueva automáticamente el token
--kubeconfig	Ruta al archivo kubeconfig
--allow-destructive	Habilitar operaciones de inicio/parada
--list-tools	Listar herramientas disponibles y salir
--mcp-config	Imprimir JSON de configuración de Claude Desktop

KFL (Lenguaje de Filtrado de Kubeshark)

Consultar tráfico usando sintaxis 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

Kubeshark se publica en el Registro MCP automáticamente en cada lanzamiento.

El server.json en este directorio es un archivo de referencia. Los metadatos reales del registro (versión, hashes SHA256) se generan automáticamente durante el flujo de trabajo de lanzamiento. Consulte .github/workflows/release.yml para más detalles.

Enlaces

• Documentación
• GitHub
• Sitio Web
• Registro MCP

Licencia

Apache-2.0