mcp-kubernetes

mcp-kubernetes

Un servidor de Model Context Protocol para Kubernetes. Permite que un cliente compatible con MCP (Claude Desktop, Claude Code, etc.) inspeccione y opere clústeres de Kubernetes en múltiples contextos, con el comportamiento controlado completamente por banderas.

El objetivo de diseño es seguro por defecto: comienza en modo solo lectura, puede limitarse a una lista permitida de namespaces y contextos, protege los namespaces del sistema contra mutaciones y restringe las operaciones peligrosas (delete, apply, exec) detrás de opciones explícitas de activación.

Características

• Multi-clúster — cada herramienta acepta un context opcional; limita qué contextos son utilizables con una lista permitida.
• Modos de acceso — read-only → read-write → admin, en capas para que un modo nunca exponga herramientas por encima de su nivel.
• Banderas de seguridad — lista permitida de namespaces, namespaces protegidos, lista permitida de contextos, además de opciones independientes para delete / apply / exec, dry-run y registro de auditoría JSON (ver más abajo).
• Autenticación estándar — usa tu kube-config (o cuenta de servicio en el clúster). El servidor no almacena credenciales.

Modelo de seguridad

Preocupación	Banderas	Predeterminado	Efecto
¿Qué puede hacer el servidor en general?	K8S_MODE	read-only	read-only expone solo lecturas; read-write añade mutaciones; admin añade herramientas destructivas. Las herramientas por encima del modo nunca se registran.
¿Qué namespaces están en alcance?	K8S_NAMESPACE_ALLOWLIST	(todos)	Cuando se establece, cualquier operación en un namespace fuera de la lista es rechazada.
¿Qué namespaces son de solo lectura para siempre?	K8S_PROTECTED_NAMESPACES	kube-system,kube-public,kube-node-lease	Pueden leerse pero nunca mutarse ni eliminarse, independientemente del modo.
¿Qué clústeres son alcanzables?	K8S_CONTEXT_ALLOWLIST	(todos)	Cuando se establece, solo estos contextos de kube-config pueden ser objetivo.
¿Puede eliminar?	K8S_ALLOW_DELETE	false	delete_resource necesita esto y modo admin.
¿Puede aplicar manifiestos?	K8S_ALLOW_APPLY	false	apply_manifest necesita esto y modo lectura-escritura.
¿Puede ejecutar comandos en pods?	K8S_ALLOW_EXEC	false	exec_in_pod necesita esto y modo admin; la herramienta ni siquiera se registra de otro modo.
Vista previa sin tocar el clúster	K8S_DRY_RUN	false	Las herramientas de escritura/admin validan y registran la intención, luego regresan sin llamar a la API.
Rastro de auditoría	K8S_AUDIT_LOG	true	Emite una línea JSON a stderr por operación protegida (ALLOW / DENY / DRY_RUN).

Las capas son independientes — p. ej., el modo admin con las tres opciones false puede reiniciar y escalar deployments pero no puede eliminar recursos ni ejecutar comandos en pods.

Herramientas

Lectura (read-only+): list_contexts, list_namespaces, list_pods, get_pod, get_pod_logs, list_deployments, list_services, list_nodes, list_events, get_resource

Escritura (read-write+): scale_deployment, restart_deployment, set_deployment_image, create_namespace, apply_manifest (necesita K8S_ALLOW_APPLY)

Admin (admin): delete_resource (necesita K8S_ALLOW_DELETE), exec_in_pod (necesita K8S_ALLOW_EXEC)

Inicio rápido — añade a tu agente

Publicado en npm como @dockndevai/mcp-kubernetes. No se necesita clonar ni compilar — tu cliente MCP lo ejecuta bajo demanda con npx. Comienza en modo read-only; consulta .env.example para cada variable y docs/CLIENTS.md para la guía completa por cliente.

Claude Code (CLI)

claude mcp add kubernetes -e KUBECONFIG_PATH="/Users/you/.kube/config" -e K8S_MODE="read-only" -- npx -y @dockndevai/mcp-kubernetes

Claude Desktop · Cursor · Windsurf — mismo bloque en claude_desktop_config.json, .cursor/mcp.json o ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — en ~/.codex/config.toml:

[mcp_servers.kubernetes]
command = "npx"
args = ["-y", "@dockndevai/mcp-kubernetes"]
env = { KUBECONFIG_PATH = "/Users/you/.kube/config", K8S_MODE = "read-only" }

VS Code (GitHub Copilot, modo Agente) — en .vscode/mcp.json:

{
  "servers": {
    "kubernetes": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

Ejecutar desde el código fuente (desarrollo)

Prefiere el paquete publicado anteriormente. Para ejecutar desde un clon:

npm install
npm run build
node dist/index.js   # with the environment variables set

Desarrollo

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

Publicación

Este servidor incluye un server.json para el registro oficial de MCP y un mcpName para la validación de propiedad en npm. Consulta PUBLISHING.md para publicar en npm y listar en el registro de MCP, Smithery, Glama, Cursor y PulseMCP.

Licencia

MIT