kubectl-mcp

Un servidor MCP (Model Context Protocol) que permite a los agentes de IA inspeccionar clústeres de Kubernetes en lenguaje natural — pregunta "¿qué pods se reiniciaron en la última hora?" y obtén una respuesta real.

Creado por Teresa Tran.

Por qué

Los asistentes de LLM son excelentes explicando comandos kubectl y pésimos ejecutándolos de forma segura. kubectl-mcp expone la inspección de clústeres de solo lectura como un conjunto de herramientas MCP que un agente puede llamar — convirtiendo "revisa mi clúster" de copiar-y-pegar-y-esperar en una conversación real.

• Solo lectura por diseño. Sin apply, sin delete, sin exec. El servidor solo inspecciona.

• Modo simulado por defecto. Incluye un clúster falso con datos de ejemplo para que puedas probarlo en 30 segundos sin un clúster real.

• Modo real cuando estés listo. Apúntalo a tu KUBECONFIG y consultará un clúster en vivo mediante el cliente oficial de Kubernetes para Python.

Related MCP server: mcp-k8s-context-server

Instalación

pip install kubectl-mcp                # mock mode (default)
pip install "kubectl-mcp[real]"        # + real-cluster support (kubernetes client)

O desde el código fuente:

git clone https://github.com/teresa-tran/kubectl-mcp.git
cd kubectl-mcp
pip install -e ".[real,dev]"

Ejecútalo de forma independiente (verificación rápida)

kubectl-mcp --help                     # show flags
kubectl-mcp --list-tools               # print every MCP tool + its schema
kubectl-mcp --demo list_pods           # run a tool once against the mock cluster
kubectl-mcp --demo find_restarted_pods --arg since_minutes=120

Conéctalo a un cliente MCP

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (mac) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp"
    }
  }
}

Para el modo de clúster real:

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp",
      "env": {
        "KUBECTL_MCP_MODE": "real",
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Reinicia Claude Desktop. Ahora deberías poder preguntar "lista los pods en el namespace de producción" y obtener una respuesta real.

Otros clientes compatibles con MCP

Cualquier cliente que hable MCP por stdio (Cursor, Cline, Continue, agentes personalizados) funciona de la misma manera — apúntalo al binario kubectl-mcp.

Herramientas expuestas

Cada herramienta tiene un JSON Schema — los LLM obtienen validación de argumentos adecuada de forma gratuita.

Configuración

Variables de entorno:

El clúster simulado

El clúster simulado por defecto viene en src/kubectl_mcp/mock_data.json e incluye:

• 3 namespaces: default, production, staging

• ~15 pods que abarcan estados saludables, en crashloop y reiniciados recientemente

• Deployments, servicios y un flujo de eventos recientes

• Algunos pods tienen contadores de reinicio > 0 para que find_restarted_pods devuelva resultados reales

Puedes sobrescribirlo configurando KUBECTL_MCP_MOCK_DATA=/ruta/a/tu.json si quieres demostrar un escenario específico.

Notas de diseño

• Solo lectura por construcción. El protocolo KubernetesBackend solo define métodos de lectura. No hay ninguna ruta de código que pueda mutar el estado del clúster — ni siquiera en modo real.

• El backend es intercambiable. MockBackend y RealBackend implementan el mismo protocolo. Añadir un tercero (por ejemplo, una instantánea en caché) es un archivo.

• Los errores son excepciones, no nulos silenciosos. ResourceNotFound, NamespaceNotFound, etc., se propagan como McpError con mensajes útiles para que el agente pueda corregir el rumbo.

• Transporte stdio. Todas las llamadas a herramientas MCP son JSON-RPC sobre stdio, cumpliendo exactamente con la especificación MCP.

Desarrollo

pip install -e ".[real,dev]"
pytest                                 # run tests
ruff check src tests                   # lint
kubectl-mcp --demo list_pods --arg namespace=production   # smoke test

Hoja de ruta

• Backend simulado con datos de ejemplo

• Backend real mediante el cliente de Python kubernetes

• Superficie de herramientas de solo lectura

• Modo --demo independiente para CI/pruebas de humo

• Soporte multi-clúster (bandera --context)

• Herramientas de métricas (CPU/memoria mediante metrics.k8s.io)

• Capa de caché opcional para consultas de alta frecuencia

Licencia

MIT © 2026 Teresa Tran