kubeview-mcp

Servidor MCP de solo lectura para depuración de Kubernetes impulsada por IA con soporte de ejecución de código

Documentación

KubeView MCP

Servidor de Model Context Protocol de solo lectura para diagnósticos de Kubernetes. En lugar de exponer docenas de herramientas, proporciona al agente un runtime de TypeScript en sandbox: una única llamada a run_code puede consultar Kubernetes, Helm, Argo Workflows y Argo CD, correlacionar los resultados y devolver solo la respuesta. Los payloads intermedios nunca pasan por la ventana de contexto del modelo. Basado en el patrón de ejecución de código con MCP.

Contexto: Expulsando llamadas de herramientas MCP de tu clúster de Kubernetes

Cómo funciona

v2 publica exactamente dos herramientas públicas: run_code y una kube_pod_exec con aprobación. Todo lo demás se descubre dentro del sandbox mediante tools.list(), tools.search() y tools.help(), siguiendo las guías de MCP de descubrimiento progresivo y llamadas programáticas.

run_code ejecuta TypeScript acotado con await de nivel superior. Una sola llamada puede listar cargas de trabajo, correlacionar eventos, obtener registros y comparar el estado de Helm sin enviar payloads intermedios de vuelta a través del modelo:

const pods = await tools.kubernetes.list({ namespace: 'payments' });
const unhealthy = pods.items.filter((p) => p.status?.phase !== 'Running');

return Promise.all(
  unhealthy.map(async (pod) => ({
    pod: pod.metadata?.name,
    logs: await tools.kubernetes.logs({
      namespace: 'payments',
      podName: pod.metadata?.name,
      tailLines: 100,
    }),
  })),
);

Aislamiento sensible — kube_pod_exec es inalcanzable desde el código en sandbox. La ejecución de nivel superior requiere elicitación MCP, está vinculada al resumen del argumento, expira después de 10 minutos y falla de forma segura. kube_port_forward nunca es una herramienta de nivel superior y está denegada dentro del modo de código por defecto. tools.disabled() informa qué política bloqueó una capacidad y si esa denegación es configurable.
Descubrimiento basado en API — Argo Workflows y Argo CD se detectan desde la API de Kubernetes, con alcance al contexto kube activo, con caché de 60 s. Una API opcional no disponible nunca bloquea el inicio.
Lecturas nativas — recursos, métricas, registros, eventos y sondeos de red pasan por la API de Kubernetes. Los releases de Helm se analizan desde Secrets o ConfigMaps del clúster; un binario local de helm es un respaldo, no un requisito.

Inicio rápido

Requisitos previos: Node.js ≥ 22 y acceso a un clúster (KUBECONFIG o cuenta de servicio dentro del clúster).

npx -y kubeview-mcp

# Claude Code
claude mcp add kubernetes -- npx kubeview-mcp

{
  "mcpServers": {
    "kubeview": {
      "command": "npx",
      "args": ["-y", "kubeview-mcp"]
    }
  }
}

En Cursor, /kubeview/code-mode inyecta la API tipada en el contexto.

Configuración

Clúster

Variable	Descripción	Predeterminado
`KUBECONFIG`	Ruta del kubeconfig	`~/.kube/config`
`MCP_KUBE_CONTEXT`	Contexto de Kubernetes; usa el contexto activo por defecto	sin definir
`MCP_K8S_SKIP_TLS_VERIFY`	Omitir verificación TLS para la API de Kubernetes (`true`/`1`)	`false`
`MCP_TIMEOUT`	Tiempo de espera de operación predeterminado en ms	predeterminado del plugin
`MCP_HIDE_SENSITIVE`	Enmascarar datos sensibles globalmente	`false`
`MCP_DISABLE_KUBERNETES_PLUGIN`	Deshabilitar el plugin de Kubernetes (`true`/`1`)	sin definir
`MCP_DISABLE_HELM_PLUGIN`	Deshabilitar el plugin de Helm (`true`/`1`)	sin definir

Modo y capacidades

Variable	Descripción	Predeterminado
`MCP_MODE`	`code` (predeterminado), `all` (alias) o `tools`	`code`
`MCP_CODE_MODE_DISABLED_TOOLS`	Denegaciones de modo de código separadas por comas; vacío habilita todo	JSON/predeterminado
`MCP_ARGO_TOOLS`	Anulación de Argo: `auto`, `on`, `off`	`auto`
`MCP_ARGOCD_TOOLS`	Anulación de Argo CD: `auto`, `on`, `off`	`auto`
`MCP_LOG_LEVEL`	`error`, `warn`, `info`, `debug`	`info`
`KUBE_MCP_FORCE_VM_SANDBOX`	Forzar `node:vm` en el runtime independiente	sin definir

Transporte HTTP

Variable	Descripción	Predeterminado
`MCP_TRANSPORT`	`stdio` o `http`	`stdio`
`MCP_HTTP_HOST` / `_PORT`	Enlace HTTP (cuando `MCP_TRANSPORT=http`)	`127.0.0.1:3000`
`MCP_HTTP_PATH`	Ruta del endpoint HTTP transmisible	`/mcp`
`MCP_HTTP_JSON_RESPONSE`	Preferir JSON sobre SSE (omite notificaciones a mitad de llamada)	`false`
`MCP_ALLOWED_HOSTS`	Lista de permitidos de hosts (requerida al enlazar a `0.0.0.0`/`::`)	predeterminados locales
`MCP_ALLOWED_ORIGINS`	Lista de permitidos de orígenes para HTTP	sin definir
`MCP_APPROVAL_STATE_SECRET`	Secreto compartido de firma de 32+ bytes; requerido para aprobaciones HTTP	efímero (stdio)
`MCP_APPROVAL_REPLAY_DIR`	Directorio absoluto de volumen compartido para aprobaciones HTTP de un solo uso	sin definir

mkdir -p /tmp/kubeview-mcp-approvals
MCP_APPROVAL_STATE_SECRET='replace-with-at-least-32-random-bytes' \
MCP_APPROVAL_REPLAY_DIR=/tmp/kubeview-mcp-approvals \
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 npx -y kubeview-mcp

Endpoint: http://127.0.0.1:3000/mcp. HTTP sigue el núcleo sin estado MCP 2026-07-28: un servidor nuevo por solicitud, sin initialize, sin Mcp-Session-Id. Cada solicitud lleva versión de protocolo, identidad del cliente y capacidades en _meta; las solicitudes modernas agregan Mcp-Method/Mcp-Name para enrutamiento de gateway. Los clientes de la era 2025 usan el respaldo sin estado del SDK en el mismo endpoint. El estado que debe sobrevivir entre llamadas debe pasarse como argumentos de herramienta o manejadores.

El modo HTTP se niega a iniciar sin ambas variables de aprobación. Las implementaciones con múltiples réplicas necesitan el mismo secreto y un directorio de reproducción compartido y escribible; el ejemplo de /tmp es solo para un proceso único. La entrada publicada en el registro MCP aún apunta a stdio.

Superficies de herramientas

`MCP_MODE`	Herramientas expuestas
sin definir / `code` / `all`	`run_code`, `kube_pod_exec`
`tools`	`kube_list`, `kube_get`, `kube_logs`, `helm`, `kube_pod_exec`, más `argo` y `argocd` detectados

Las herramientas de dominio usan un discriminador operation:

helm — list | get | debug
argo — list | get | logs | cron_list (cuando Workflow o CronWorkflow es detectable)
argocd — list | get | resources | logs | history | status (cuando Application es detectable, o con ARGOCD_SERVER + ARGOCD_AUTH_TOKEN)

El descubrimiento se almacena en caché por contexto kube durante 60 s. Las APIs opcionales faltantes se omiten, no son fatales.

Modo de código

El modo de código es el predeterminado (MCP_MODE=code). El agente escribe TypeScript corto contra un global tipado tools en lugar de llamar a docenas de herramientas MCP.

Dentro de run_code:

Espacios de nombres tipados tools para Kubernetes, Helm y cualquier capacidad de Argo detectada, generados desde esquemas en vivo para que los parámetros no puedan alucinarse.
Descubrimiento progresivo: tools.list(), tools.search(), tools.help() y tools.disabled() (el último informa por qué se bloqueó una capacidad).
Un runtime bloqueado con solo console y tools en alcance — sin sistema de archivos, sin red, sin process.

Capacidad	Dentro de `run_code`	Herramienta de nivel superior
`kube_pod_exec`	Nunca disponible	Requiere aprobación de usuario por llamada (10 min, vinculada a argumentos)
`kube_port_forward`	Denegada por defecto (configurable)	Nunca expuesta
Todo lo demás	Disponible	Solo cuando `MCP_MODE=tools`

La aprobación de exec en pods usa elicitación MCP y falla de forma segura. El lanzador independiente npm run code-mode no tiene una interfaz de aprobación confiable, por lo que siempre deniega exec en pods.

Personalización de denegaciones

MCP_CODE_MODE_DISABLED_TOOLS (separado por comas) controla qué capacidades se bloquean dentro de run_code. Orden de resolución:

Variable de entorno MCP_CODE_MODE_DISABLED_TOOLS
disabledTools en kube-mcp.code-mode.json
Predeterminado: ["kube_port_forward"]

Un valor de entorno vacío limpia la lista. kube_pod_exec no se puede agregar — está bloqueado permanentemente.

Protocolo

MCP 2026-07-28:

Contratos de entrada/salida JSON Schema 2020-12 con validación del lado del servidor
structuredContent legible por máquina con respaldo de texto
Anotaciones precisas de read-only, destructive, idempotent, open-world
Ordenamiento determinista de herramientas con sugerencias de caché para superficies fijas vs. dependientes de descubrimiento
HTTP sin estado con descubrimiento y enrutamiento basado en encabezados (Mcp-Method, Mcp-Name)
Fallos de ejecución devueltos como errores de herramienta; errores de protocolo reservados para solicitudes malformadas

Desarrollo local

git clone https://github.com/mikhae1/kubeview-mcp.git
cd kubeview-mcp && npm install

npm run build      # compile
npm start          # build + run
npm test           # jest suite
npm run typecheck  # tsc --noEmit

# Invoke a tool directly
npm run command -- kube_list --namespace=default

Las pruebas de protocolo fijan el cliente SDK v2 a 2026-07-28 y enrutan a través del manejador del servidor en proceso (sin puertos abiertos):

npm test -- --runInBand \
  tests/server/StreamableHttpTransport.integration.test.ts \
  tests/server/StreamableHttpRuntime.test.ts \
  tests/server/TransportConfig.test.ts \
  tests/compat/McpSdkCompatibility.test.ts

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un issue o un pull request.