Kubernetes

Conéctate al clúster de Kubernetes y gestiona pods, deployments, servicios.

GitHub
1.6k
Prueba este MCPPatrocinado

Documentación

Servidor MCP Kubernetes

CI Language Kubernetes Docker Stars Issues PRs Welcome Last Commit

Servidor MCP que puede conectarse a un clúster de Kubernetes y gestionarlo. Admite la carga de kubeconfig desde múltiples fuentes en orden de prioridad.

https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed

Instalación y Uso

Requisitos Previos

Antes de usar este servidor MCP con cualquier herramienta, asegúrate de tener:

  1. kubectl instalado y en tu PATH
  2. Un archivo kubeconfig válido con contextos configurados
  3. Acceso a un clúster de Kubernetes configurado para kubectl (por ejemplo, minikube, Rancher Desktop, GKE, etc.)
  4. Helm v3 instalado y en tu PATH (no se requiere Tiller). Opcional si no planeas usar Helm.

Puedes verificar tu conexión ejecutando kubectl get pods en una terminal para asegurarte de que puedes conectarte a tu clúster sin problemas de credenciales.

Por defecto, el servidor carga kubeconfig desde ~/.kube/config. Para opciones de autenticación adicionales (variables de entorno, rutas personalizadas, etc.), consulta ADVANCED_README.md.

Claude Code

Agrega el servidor MCP a Claude Code usando el comando integrado:

claude mcp add kubernetes -- npx mcp-server-kubernetes

Esto configurará automáticamente el servidor en tu configuración MCP de Claude Code.

Codex

Agrega el servidor MCP a Codex CLI usando el comando integrado:

codex mcp add kubernetes -- npx mcp-server-kubernetes

Esto registra el servidor globalmente en ~/.codex/config.toml y hace que sus herramientas estén disponibles en todas las sesiones de Codex.

Claude Desktop

Agrega la siguiente configuración a tu archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

Conector Claude Desktop vía mcpb

MCP Server Kubernetes también está disponible como una extensión de mcpb (anteriormente dxt). En Claude Desktop, ve a Configuración (Cmd+, en Mac) -> Extensiones -> Explorar Extensiones y desplázate para encontrar mcp-server-kubernetes en el modal. Instálalo e instalará y utilizará kubectl a través de la línea de comandos y tu kubeconfig.

Para instalar manualmente, también puedes obtener el .mcpb yendo a la última Release y descargándolo.

VS Code

Install Kubernetes MCP in VS Code

Para la integración con VS Code, puedes usar el servidor MCP con extensiones que soporten el Protocolo de Contexto de Modelo:

  1. Instala una extensión MCP compatible (como Claude Dev o clientes MCP similares)
  2. Configura la extensión para usar este servidor:
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "description": "Kubernetes cluster management and operations"
    }
  }
}

Cursor

Cursor soporta servidores MCP a través de su integración de IA. Agrega el servidor a tu configuración MCP de Cursor:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

El servidor se conectará automáticamente a tu contexto kubectl actual. Puedes verificar la conexión pidiendo al asistente de IA que liste tus pods o cree un deployment de prueba.

Uso con mcp-chat

mcp-chat es un cliente de chat CLI para servidores MCP. Puedes usarlo para interactuar con el servidor Kubernetes.

npx mcp-chat --server "npx mcp-server-kubernetes"

Alternativamente, pásale tu archivo de configuración existente de Claude Desktop de arriba (Linux debe pasar la ruta correcta al config):

Mac:

npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"

Windows:

npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"

Características

  • Conectarse a un clúster de Kubernetes
  • API kubectl unificada para gestionar recursos
    • Obtener o listar recursos con kubectl_get
    • Describir recursos con kubectl_describe
    • Listar recursos con kubectl_get
    • Crear recursos con kubectl_create
    • Aplicar manifiestos YAML con kubectl_apply
    • Eliminar recursos con kubectl_delete
    • Obtener registros con kubectl_logs
    • Gestionar contextos kubectl con kubectl_context
    • Explicar recursos de Kubernetes con explain_resource
    • Listar recursos de API con list_api_resources
    • Escalar recursos con kubectl_scale
    • Actualizar campo(s) de un recurso con kubectl_patch
    • Gestionar despliegues de rollouts con kubectl_rollout
    • Ejecutar cualquier comando kubectl con kubectl_generic
    • Verificar conexión con ping
  • Operaciones avanzadas
    • Escalar deployments con kubectl_scale (reemplaza el legado scale_deployment)
    • Reenvío de puertos a pods y servicios con port_forward
    • Ejecutar operaciones de Helm
      • Instalar, actualizar y desinstalar charts
      • Soporte para valores personalizados, repositorios y versiones
      • Instalación basada en plantillas (helm_template_apply) para evitar problemas de autenticación
      • Desinstalación basada en plantillas (helm_template_uninstall) para evitar problemas de autenticación
    • Operaciones de limpieza de pods
      • Limpiar pods problemáticos (cleanup_pods) en estados: Evicted, ContainerStatusUnknown, Completed, Error, ImagePullBackOff, CrashLoopBackOff
    • Operaciones de gestión de nodos
      • Cordoning, draining y uncordoning de nodos (node_management) para operaciones de mantenimiento y escalado
  • Prompt de solución de problemas (k8s-diagnose)
    • Guía a través de un flujo sistemático de solución de problemas de Kubernetes para pods basado en una palabra clave y un namespace opcional.
  • Modo no destructivo para acceso de solo lectura y creación/actualización a clústeres
  • Enmascaramiento de secretos por seguridad (enmascara datos sensibles en comandos kubectl get secrets, no afecta los registros)
  • Observabilidad OpenTelemetry (opt-in)
    • Trazado distribuido para todas las llamadas de herramientas
    • Exportación a Jaeger, Tempo, Grafana o cualquier backend OTLP
    • Estrategias de muestreo configurables
    • Atributos de span enriquecidos (nombre de herramienta, duración, contexto K8s, errores)
    • Consulta docs/OBSERVABILITY.md para detalles

Observabilidad

El servidor MCP Kubernetes incluye integración opcional de OpenTelemetry para observabilidad integral. Esta característica está deshabilitada por defecto y puede habilitarse mediante variables de entorno o configuración de Helm.

Inicio Rápido

Habilita la observabilidad con variables de entorno:

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

npx mcp-server-kubernetes

Qué se Traza

  • Todas las llamadas de herramientas: kubectl_get, kubectl_apply, kubectl_logs, etc.
  • Duración de ejecución: Cuánto tarda cada operación
  • Estado de éxito/fallo: Seguimiento automático de errores
  • Contexto de Kubernetes: Namespace, contexto, tipo de recurso
  • Metadatos enriquecidos: Host, proceso y atributos personalizados

Backends Soportados

Funciona con cualquier backend compatible con OTLP:

  • Jaeger (código abierto)
  • Grafana Tempo (código abierto)
  • Grafana Cloud (comercial)
  • Datadog, New Relic, Honeycomb, Lightstep, AWS X-Ray

Configuración

Consulta docs/OBSERVABILITY.md para documentación completa que incluye:

  • Opciones de configuración
  • Ejemplos de despliegue (Kubernetes, Helm, Claude Code)
  • Estrategias de muestreo
  • Mejores prácticas de producción
  • Guía de solución de problemas

Ejemplo con Jaeger

# Start Jaeger
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Enable telemetry
export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_TRACES_SAMPLER=always_on

# Run server
npx mcp-server-kubernetes

# View traces: http://localhost:16686

Prompts

El servidor MCP Kubernetes incluye prompts especializados para ayudar con operaciones de diagnóstico comunes.

Prompt /k8s-diagnose

Este prompt proporciona un flujo sistemático de solución de problemas para pods de Kubernetes. Acepta un keyword para identificar pods relevantes y un namespace opcional para acotar la búsqueda. La salida del prompt te guiará a través de un flujo autónomo de solución de problemas, proporcionando instrucciones para identificar problemas, recopilar evidencia y sugerir pasos de remediación.

Desarrollo Local

Asegúrate de tener bun instalado. Clona el repositorio e instala las dependencias:

git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
bun install

Flujo de Trabajo de Desarrollo

  1. Inicia el servidor en modo de desarrollo (observa los cambios de archivos):
bun run dev
  1. Ejecuta las pruebas unitarias:
bun run test
  1. Compila el proyecto:
bun run build
  1. Pruebas locales con Inspector
npx @modelcontextprotocol/inspector node dist/index.js
# Follow further instructions on terminal for Inspector link
  1. Pruebas locales con Claude Desktop
{
  "mcpServers": {
    "mcp-server-kubernetes": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
    }
  }
}
  1. Pruebas locales con mcp-chat
bun run chat

Contribuciones

Consulta el archivo CONTRIBUTING.md para más detalles.

Avanzado

Modo No Destructivo

Puedes ejecutar el servidor en un modo no destructivo que deshabilita todas las operaciones destructivas (eliminar pods, eliminar deployments, eliminar namespaces, etc.):

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx mcp-server-kubernetes

Para la configuración de Claude Desktop con modo no destructivo:

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

Comandos Disponibles en Modo No Destructivo

Todas las operaciones de solo lectura y creación/actualización de recursos permanecen disponibles:

  • Información de Recursos: kubectl_get, kubectl_describe, kubectl_logs, explain_resource, list_api_resources
  • Creación/Modificación de Recursos: kubectl_apply, kubectl_create, kubectl_scale, kubectl_patch, kubectl_rollout
  • Operaciones de Helm: install_helm_chart, upgrade_helm_chart, helm_template_apply, helm_template_uninstall
  • Conectividad: port_forward, stop_port_forward
  • Gestión de Contextos: kubectl_context

Comandos Deshabilitados en Modo No Destructivo

Las siguientes operaciones destructivas están deshabilitadas:

  • kubectl_delete: Eliminar cualquier recurso de Kubernetes
  • uninstall_helm_chart: Desinstalar charts de Helm
  • cleanup: Limpieza de recursos gestionados
  • cleanup_pods: Limpiar pods problemáticos
  • node_management: Operaciones de gestión de nodos (puede drenar nodos)
  • kubectl_generic: Acceso general a comandos kubectl (puede incluir operaciones destructivas)
  • exec_in_pod: Ejecución de comandos arbitrarios dentro de un pod (puede leer tokens de cuenta de servicio y cambiar estado)

Para características avanzadas adicionales, consulta el ADVANCED_README.md y también la carpeta docs para información específica sobre helm_install, helm_template_apply, gestión de nodos y limpieza de pods.

Arquitectura

Consulta este enlace de DeepWiki para una visión general de arquitectura más profunda creada por Devin.

Esta sección describe la arquitectura de alto nivel del servidor MCP Kubernetes.

Flujo de Solicitudes

El diagrama de secuencia a continuación ilustra cómo fluyen las solicitudes a través del sistema:

sequenceDiagram
    participant Client
    participant Transport as Transport Layer
    participant Server as MCP Server
    participant Filter as Tool Filter
    participant Handler as Request Handler
    participant K8sManager as KubernetesManager
    participant K8s as Kubernetes API

    Note over Transport: StdioTransport or<br>SSE Transport

    Client->>Transport: Send Request
    Transport->>Server: Forward Request

    alt Tools Request
        Server->>Filter: Filter available tools
        Note over Filter: Remove destructive tools<br>if in non-destructive mode
        Filter->>Handler: Route to tools handler

        alt kubectl operations
            Handler->>K8sManager: Execute kubectl operation
            K8sManager->>K8s: Make API call
        else Helm operations
            Handler->>K8sManager: Execute Helm operation
            K8sManager->>K8s: Make API call
        else Port Forward operations
            Handler->>K8sManager: Set up port forwarding
            K8sManager->>K8s: Make API call
        end

        K8s-->>K8sManager: Return result
        K8sManager-->>Handler: Process response
        Handler-->>Server: Return tool result
    else Resource Request
        Server->>Handler: Route to resource handler
        Handler->>K8sManager: Get resource data
        K8sManager->>K8s: Query API
        K8s-->>K8sManager: Return data
        K8sManager-->>Handler: Format response
        Handler-->>Server: Return resource data
    end

    Server-->>Transport: Send Response
    Transport-->>Client: Return Final Response

Consulta este enlace de DeepWiki para una visión general de arquitectura más profunda creada por Devin.

Publicación de Nueva Versión

Ve a la página de releases, haz clic en "Draft New Release", haz clic en "Choose a tag" y crea una nueva etiqueta escribiendo un nuevo número de versión usando el formato semver "v{major}.{minor}.{patch}". Luego, escribe un título de release "Release v{major}.{minor}.{patch}" y descripción/changelog si es necesario y haz clic en "Publish Release".

Esto creará una nueva etiqueta que activará una nueva compilación de release a través del flujo de trabajo cd.yml. Una vez exitoso, la nueva versión se publicará en npm. Ten en cuenta que no hay necesidad de actualizar manualmente la versión en package.json, ya que el flujo de trabajo actualizará automáticamente el número de versión en el archivo package.json y enviará un commit a main.

No planificado

Agregar clústeres a kubectx.

Historial de Estrellas

Star History Chart

🖊️ Citar

Si encuentras útil este repositorio, por favor cita:

@software{Patel_MCP_Server_Kubernetes_2024,
author = {Patel, Paras and Sonwalkar, Suyog},
month = jul,
title = {{MCP Server Kubernetes}},
url = {https://github.com/Flux159/mcp-server-kubernetes},
version = {2.5.0},
year = {2024}
}