KubeAid MCP

Un servidor MCP para clústeres de Kubernetes gestionados con KubeAid. Conéctalo a Claude Code, Claude Desktop, Cursor o a cualquier cliente compatible con MCP y haz preguntas como «¿qué apps están desincronizadas?», «¿por qué está degradado kube-prometheus?» o «sincroniza la app cert-manager»: el modelo responde llamando a las herramientas de este servidor, que hablan con tu clúster a través de tus propias credenciales kubeconfig.

Construido en TypeScript sobre el @modelcontextprotocol/sdk oficial y @kubernetes/client-node.

Autor: Deep Poharkar

¿Por qué es específico de KubeAid?

KubeAid gestiona los clústeres al estilo GitOps: cada aplicación es una Application de ArgoCD generada desde tu repositorio kubeaid-config, y la auto-sincronización está deshabilitada por defecto: la divergencia entre Git y el clúster es normal y espera a una sincronización deliberada. Un asistente genérico de Kubernetes no entiende ese flujo de trabajo. Este servidor sí:

• El CR Application de ArgoCD es un ciudadano de primera clase: estado de sincronización, salud, condiciones de error y recursos divergentes están a una sola llamada de herramienta.

• La sincronización se modela como la decisión explícita de «desplegar ahora» que es en KubeAid: protegida por una flag de opt-in, con soporte de dry_run, y nunca permitida en contextos que marques como protegidos.

• Los prompts incluidos codifican los hábitos operativos de KubeAid: revisa la divergencia antes de sincronizar, arregla las cosas en el repositorio kubeaid-config en lugar de editar el clúster a mano.

Herramientas

Herramientas de lectura — siempre registradas:

Herramientas de escritura — registradas solo cuando KUBEAID_MCP_ALLOW_WRITES=true:

Cada herramienta acepta un argumento opcional context para apuntar a cualquier clúster de tu kubeconfig desde un único proceso del servidor.

Prompts

Los prompts aparecen como comandos de barra / elementos de menú en el cliente y guían al modelo a través de un flujo de trabajo usando las herramientas anteriores:

Inicio rápido

Requiere Node.js 20+.

git clone <your-repo-url> kubeaid-mcp
cd kubeaid-mcp
npm install
npm run build

Claude Code

claude mcp add kubeaid -- node "$(pwd)/dist/index.js"

De solo lectura por defecto. Para habilitar escrituras sin poder tocar producción:

claude mcp add kubeaid \
  -e KUBEAID_MCP_ALLOW_WRITES=true \
  -e KUBEAID_MCP_PROTECTED_CONTEXTS=prod-cluster-1,prod-cluster-2 \
  -- node "$(pwd)/dist/index.js"

Claude Desktop

Habilita Settings → Developer → Local MCP servers y luego añade al archivo de configuración que se abre en esa página:

{
  "mcpServers": {
    "kubeaid": {
      "command": "node",
      "args": ["/absolute/path/to/kubeaid-mcp/dist/index.js"],
      "env": {
        "KUBEAID_MCP_ALLOW_WRITES": "true",
        "KUBEAID_MCP_PROTECTED_CONTEXTS": "prod-cluster-1"
      }
    }
  }
}

Cierra y vuelve a abrir la aplicación por completo después.

Configuración

Toda la configuración se hace mediante variables de entorno, que se leen una vez al arrancar:

Modelo de seguridad

Tres capas independientes:

1. Control de capacidades — con las escrituras deshabilitadas (el valor por defecto), las herramientas mutadoras nunca se registran, por lo que el modelo ni siquiera puede verlas.

2. Contextos protegidos — cada manejador de mutación vuelve a comprobar el contexto de destino contra KUBEAID_MCP_PROTECTED_CONTEXTS y rechaza los protegidos, sin importar lo que pida el modelo.

3. Confirmación del cliente — las herramientas llevan anotaciones MCP readOnlyHint/destructiveHint, de modo que los clientes que se comportan correctamente te piden confirmación antes de llamadas arriesgadas.

El servidor no guarda credenciales propias; solo puede hacer aquello para lo que tu identidad de kubeconfig ya está autorizada mediante RBAC.

Desarrollo

npm run typecheck   # strict TS, no emit
npm run build       # compile to dist/
npm run smoke       # spawn the server, MCP handshake, list tools + prompts
KUBEAID_MCP_ALLOW_WRITES=true npm run smoke   # verify write tools register

La prueba de humo no necesita clúster: utiliza el protocolo JSON-RPC sin procesar a través de stdio.

Hoja de ruta

• check_chart_updates: comparar las versiones de los charts desplegados con el directorio upstream argocd-helm-charts de KubeAid.

• Ayudas para sealed-secrets: listar el estado de SealedSecret, marcar los unseals fallidos.

• Herramientas de Prometheus/Alertmanager: mostrar alertas activas del stack kube-prometheus que KubeAid incluye.

Agradecimientos

• KubeAid, de Obmondo — el stack de gestión de clústeres para el que está construido este servidor.

• Argo CD — el motor GitOps que subyace a KubeAid.

Licencia

MIT © 2026 Deep Poharkar