Kubernetes

mcp-kubernetes

mcp-kubernetes es un servidor del Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con clústeres de Kubernetes. Actúa como un puente entre herramientas de IA (como Claude, Cursor y GitHub Copilot) y Kubernetes, traduciendo solicitudes en lenguaje natural a operaciones de Kubernetes y devolviendo los resultados en un formato que las herramientas de IA pueden entender.

Permite a las herramientas de IA:

• Consultar recursos de Kubernetes
• Ejecutar comandos de kubectl
• Gestionar clústeres de Kubernetes mediante interacciones en lenguaje natural
• Diagnosticar e interpretar los estados de los recursos de Kubernetes

Cómo funciona

Cómo instalar

Las imágenes de contenedor ya no se producen ni se admiten. Instala un binario de la versión publicada localmente y configura tu cliente MCP para ejecutarlo como un subproceso stdio.

Local

# For Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# For MacOS
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Configura tus servidores MCP en Claude Desktop, Cursor, ChatGPT Copilot, Github Copilot y otros clientes de IA compatibles, por ejemplo:

{
  "mcpServers": {
    "kubernetes": {
      "command": "<path of binary 'mcp-kubernetes'>",
      "args": ["--transport", "stdio"],
      "env": {
        "KUBECONFIG": "<your-kubeconfig-path>"
      }
    }
  }
}

Opciones

Variables de entorno:

• KUBECONFIG: Ruta a tu archivo kubeconfig, por ejemplo /home/<username>/.kube/config.
• USE_LEGACY_TOOLS: Establécelo en true para usar múltiples herramientas especializadas de kubectl en lugar de la herramienta unificada call_kubectl (predeterminado: false).

Argumentos de línea de comandos:

Usage of ./mcp-kubernetes:
      --access-level string       Access level (readonly, readwrite, or admin) (default "readonly")
      --additional-tools string   Comma-separated list of additional tools to support (kubectl is always enabled). Available: helm,cilium,hubble
      --allow-namespaces string   Comma-separated list of namespaces to allow (empty means all allowed)
      --otlp-endpoint string      OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317, default "")
      --timeout int               Timeout for command execution in seconds, default is 60s (default 60)
      --transport string          Transport mechanism to use (stdio only) (default "stdio")

Herramientas unificadas vs. heredadas

De forma predeterminada, mcp-kubernetes utiliza una única herramienta unificada call_kubectl que consolida todas las operaciones de kubectl en una sola interfaz de herramienta. Esto reduce significativamente el consumo de contexto mientras mantiene toda la funcionalidad.

Para usar el modo heredado con múltiples herramientas especializadas (6-7 herramientas separadas), establece la variable de entorno:

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "env": {
        "USE_LEGACY_TOOLS": "true"
      }
    }
  }
}

Niveles de acceso

El indicador --access-level controla qué operaciones están permitidas:

• readonly (predeterminado): Solo se permiten operaciones de lectura (get, describe, logs, etc.)
• readwrite: Se permiten operaciones de lectura y escritura (create, delete, apply, etc.)
• admin: Se permiten todas las operaciones, incluidas las administrativas (cordon, drain, taint, etc.)

Las herramientas y operaciones se filtran en el momento del registro según el nivel de acceso, por lo que los asistentes de IA solo ven las operaciones que realmente pueden usar.

Ejemplos de configuración:

// Read-only access (default)
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes"
    }
  }
}

// Read-write access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "readwrite"]
    }
  }
}

// Admin access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "admin"]
    }
  }
}

Uso

Haz cualquier pregunta sobre el clúster de Kubernetes en tu cliente de IA. Las herramientas MCP facilitan que los asistentes de IA comprendan y usen las operaciones de kubectl.

Ejemplos de consultas

What is the status of my Kubernetes cluster?

What is wrong with my nginx pod?

Show me all deployments in the production namespace

Scale my web deployment to 5 replicas

Check if I have permission to create pods

What is my current kubectl context?

List all available kubectl contexts

Switch to the production context

Herramientas disponibles

Herramienta unificada (predeterminada)

De forma predeterminada, mcp-kubernetes utiliza una única herramienta unificada call_kubectl que maneja todas las operaciones de kubectl. Este enfoque reduce significativamente el consumo de contexto en comparación con el enfoque heredado de múltiples herramientas.

call_kubectl - Ejecuta comandos de kubectl

• Disponible en: Todos los niveles de acceso (operaciones filtradas por nivel de acceso)
• Parámetros:
  • command: El comando completo de kubectl a ejecutar, incluido el prefijo 'kubectl' (por ejemplo, "kubectl get pods -n default", "kubectl apply -f deployment.yaml")
• Ejemplos:

  # Get pods
  command: "kubectl get pods -n default"
  
  # Apply configuration
  command: "kubectl apply -f deployment.yaml"
  
  # Scale deployment
  command: "kubectl scale deployment nginx --replicas=3"
  

Herramientas heredadas (opcionales)

Cuando USE_LEGACY_TOOLS=true, el servidor mcp-kubernetes proporciona múltiples herramientas especializadas de kubectl que agrupan operaciones relacionadas. Las herramientas se filtran automáticamente según tu nivel de acceso.

Herramientas de Kubectl

# Get all pods
operation: "get"
resource: "pods"
args: "--all-namespaces"

# Apply a configuration
operation: "apply"
resource: ""
args: "-f deployment.yaml"

# Drain a node (admin only)
operation: "drain"
resource: "node"
args: "worker-1 --ignore-daemonsets"

# Add a taint (admin only)
operation: "taint"
resource: "nodes"
args: "worker-1 key=value:NoSchedule"

# Scale a deployment
operation: "scale"
resource: "deployment"
args: "nginx --replicas=3"

# Check rollout status
operation: "rollout"
resource: "status"
args: "deployment/nginx"

# Add a label
operation: "label"
resource: "pods"
args: "nginx-pod app=web"

# Set image
operation: "set"
resource: "image"
args: "deployment/nginx nginx=nginx:latest"

# View logs
operation: "logs"
resource: ""
args: "nginx-pod -f"

# Execute command in pod
operation: "exec"
resource: ""
args: "nginx-pod -- ls /app"

# Get cluster info
operation: "cluster-info"
resource: ""
args: ""

# Explain pod spec
operation: "explain"
resource: "pod.spec"
args: "--recursive"

# Check permissions
operation: "auth"
resource: "can-i"
args: "create pods"

# Approve certificate
operation: "certificate"
resource: "approve"
args: "csr-name"

# Get current context
operation: "config"
resource: "current-context"
args: ""

# List all contexts
operation: "config"
resource: "get-contexts"
args: ""

# Switch context (readwrite/admin only)
operation: "config"
resource: "use-context"
args: "my-cluster-context"

Herramientas adicionales

command: "list --all-namespaces"

command: "status"

command: "status"
command: "observe observe --namespace backend-jobs  --from-label 'app=web'"
command: "list nodes"

Telemetría

La recopilación de telemetría está activada de forma predeterminada.

Para optar por no participar, establece la variable de entorno KUBERNETES_MCP_COLLECT_TELEMETRY=false.

Soporte de OpenTelemetry

El servidor mcp-kubernetes admite la exportación de datos de telemetría mediante el Protocolo OpenTelemetry (OTLP). Puedes configurar un endpoint OTLP para enviar trazas a cualquier backend compatible con OpenTelemetry:

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--otlp-endpoint", "localhost:4317"]
    }
  }
}

Desarrollo

Cómo inspeccionar las solicitudes y respuestas del servidor MCP:

npx @modelcontextprotocol/inspector <path of binary 'mcp-kubernetes'>

Contribuciones

Este proyecto acepta contribuciones y sugerencias. La mayoría de las contribuciones requieren que aceptes un Acuerdo de Licencia de Contribuyente (CLA) que declare que tienes el derecho de otorgarnos, y de hecho lo haces, los derechos para usar tu contribución. Para más detalles, visita https://cla.opensource.microsoft.com.

Cuando envías una solicitud de extracción, un bot de CLA determinará automáticamente si necesitas proporcionar un CLA y decorará el PR de manera apropiada (por ejemplo, verificación de estado, comentario). Simplemente sigue las instrucciones proporcionadas por el bot. Solo necesitarás hacer esto una vez en todos los repositorios que usan nuestro CLA.

Este proyecto ha adoptado el Código de Conducta de Código Abierto de Microsoft. Para más información, consulta las Preguntas Frecuentes sobre el Código de Conducta o contacta a opencode@microsoft.com con cualquier pregunta o comentario adicional.

Marcas comerciales

Este proyecto puede contener marcas comerciales o logotipos de proyectos, productos o servicios. El uso autorizado de marcas comerciales o logotipos de Microsoft está sujeto y debe seguir las Directrices de Marcas Comerciales y Marca de Microsoft. El uso de marcas comerciales o logotipos de Microsoft en versiones modificadas de este proyecto no debe causar confusión ni implicar patrocinio de Microsoft. Cualquier uso de marcas comerciales o logotipos de terceros está sujeto a las políticas de esos terceros.