Kubernetes Server

mcp-kubernetes-server

El mcp-kubernetes-server es un servidor que implementa el Protocolo de Contexto de Modelos (MCP) para permitir que asistentes de IA (como Claude, Cursor y GitHub Copilot) interactúen con clústeres de Kubernetes. Actúa como un puente, traduciendo solicitudes en lenguaje natural de estos asistentes en operaciones de Kubernetes y devolviendo los resultados.

Permite a los asistentes 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

El mcp-kubernetes-server actúa como intermediario entre los asistentes de IA (que admiten el Protocolo de Contexto de Modelos) y su clúster de Kubernetes. Recibe solicitudes en lenguaje natural de estos asistentes, las traduce en comandos kubectl o llamadas directas a la API de Kubernetes, y las ejecuta contra el clúster de destino. El servidor luego procesa los resultados y devuelve una respuesta estructurada, lo que permite una interacción fluida con su entorno de Kubernetes a través del asistente de IA.

Cómo Instalar

Requisitos Previos

Antes de instalar mcp-kubernetes-server, asegúrese de tener lo siguiente:

• Un clúster de Kubernetes funcional.
• Un archivo kubeconfig configurado correctamente para acceder a su clúster de Kubernetes (el servidor requiere este archivo para la interacción).
• La herramienta de línea de comandos kubectl instalada y en el PATH de su sistema (utilizada por el servidor para ejecutar muchos comandos de Kubernetes).
• La herramienta de línea de comandos helm instalada y en el PATH de su sistema (utilizada por el servidor para operaciones con gráficos de Helm).
• Python >= 3.11, si planea instalar y ejecutar el servidor directamente usando uvx (sin Docker).

Docker

Obtenga su archivo kubeconfig para su clúster de Kubernetes y configúrelo en mcpServers (reemplace la ruta src con la ruta de su kubeconfig):

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/home/username/.kube/config,dst=/home/mcp/.kube/config",
        "ghcr.io/feiskyer/mcp-kubernetes-server"
      ]
    }
  }
}

UVX

Para ejecutar el servidor usando uvx (una herramienta incluida con uv, el empaquetador de Python), primero asegúrese de que uv esté instalado:

# For Linux and MacOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# 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

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

{
  "mcpServers": {
    "kubernetes": {
      "command": "uvx",
      "args": [
        "mcp-kubernetes-server"
      ],
      "env": {
        "KUBECONFIG": "<your-kubeconfig-path>"
      }
    }
  }
}

Opciones del Servidor MCP

usage: main.py [-h] [--disable-kubectl] [--disable-helm] [--disable-write]
               [--disable-delete] [--transport {stdio,sse,streamable-http}]
               [--host HOST] [--port PORT]

MCP Kubernetes Server

options:
  -h, --help            show this help message and exit
  --disable-kubectl     Disable kubectl command execution
  --disable-helm        Disable helm command execution
  --disable-write       Disable write operations
  --disable-delete      Disable delete operations
  --transport {stdio,sse,streamable-http}
                        Transport mechanism to use (stdio or sse or streamable-http)
  --host HOST           Host to use for sse or streamable-http server
  --port PORT           Port to use for sse or streamable-http server

Uso

Una vez que el mcp-kubernetes-server esté instalado y configurado en su cliente de IA (usando los fragmentos JSON proporcionados en la sección 'Cómo instalar' para Docker o UVX), puede comenzar a interactuar con su clúster de Kubernetes mediante lenguaje natural. Por ejemplo, puede preguntar:

What is the status of my Kubernetes cluster?

What is wrong with my nginx pod?

Verificando el servidor: Si está ejecutando el servidor con transporte stdio (común para la ejecución directa de uvx), el cliente de IA normalmente iniciará y gestionará el proceso del servidor. Para transportes sse o streamable-http, el servidor se ejecuta de forma independiente. Usted lo habría iniciado manualmente (por ejemplo, uvx mcp-kubernetes-server --transport sse) y debería ver una salida en su terminal indicando que se está ejecutando (por ejemplo, INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)). También puede verificar si hay mensajes de error en la terminal del servidor si el cliente de IA no logra conectarse.

Herramientas Disponibles

El mcp-kubernetes-server proporciona un conjunto completo de herramientas para interactuar con clústeres de Kubernetes, categorizadas por tipo de operación:

Desarrollo

Cómo ejecutar el proyecto localmente:

uv run -m src.mcp_kubernetes_server.main

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

npx @modelcontextprotocol/inspector uv run -m src.mcp_kubernetes_server.main

Solución de problemas

Aquí hay algunos problemas comunes y sus soluciones al trabajar con mcp-kubernetes-server:

Problema: mcp-kubernetes-server no puede conectarse al clúster de Kubernetes o informa errores de autenticación. Solución:

• Asegúrate de que tu archivo kubeconfig esté configurado correctamente y apunte al clúster deseado.
• Verifica que la ruta a tu archivo kubeconfig esté especificada correctamente en la configuración de mcpServers (para Docker, asegúrate de que la ruta de montaje sea correcta; para uvx, asegúrate de que la variable de entorno KUBECONFIG esté configurada correctamente).
• Comprueba que las credenciales en tu kubeconfig tengan los permisos necesarios para realizar operaciones en el clúster. Puedes probar esto con kubectl directamente (por ejemplo, kubectl get pods).

Problema: Los comandos kubectl o helm devuelven un error como "command not found" o están deshabilitados. Solución:

• Si se ejecuta mediante uvx, asegúrate de que kubectl y/o helm estén instalados en tu sistema y disponibles en tu PATH. Consulta la sección "Requisitos previos" para obtener orientación sobre la instalación.
• Si ves un mensaje como "Write operations are not allowed" o "Delete operations are not allowed", el servidor podría haberse iniciado con banderas como --disable-kubectl, --disable-helm, --disable-write o --disable-delete. Revisa el comando de inicio del servidor y la sección "Opciones del servidor MCP" en el README para obtener detalles sobre estas banderas.

Problema: ¿Cómo puedo ver las solicitudes y respuestas sin procesar entre mi cliente de IA y el mcp-kubernetes-server? Solución:

• Puedes usar la herramienta @modelcontextprotocol/inspector como se menciona en la sección "Desarrollo": npx @modelcontextprotocol/inspector uv run -m src.mcp_kubernetes_server.main. Esto te mostrará los mensajes MCP que se intercambian.

Problema: El servidor se inicia pero el cliente de IA no puede conectarse. Solución:

• Si se usa el transporte stdio (predeterminado para la ejecución directa de uvx), asegúrate de que tu cliente de IA esté configurado para lanzar el comando mcp-kubernetes-server correctamente.
• Si se usa el transporte sse o streamable-http, asegúrate de que el host y el puerto configurados en el mcp-kubernetes-server (por ejemplo, --host 0.0.0.0 --port 8000) sean accesibles desde donde se ejecuta tu cliente de IA. Verifica las reglas de firewall o problemas de configuración de red. Además, verifica que el cliente de IA esté configurado con la URL correcta para el servidor.

Contribución

Este proyecto es de código abierto, disponible en GitHub en feiskyer/mcp-kubernetes-server y licenciado bajo la Apache License.

Si deseas contribuir al proyecto, sigue estas pautas:

1. Haz un fork del repositorio y clónalo en tu máquina local.
2. Crea una nueva rama para tus cambios.
3. Realiza tus cambios y haz commit con un mensaje de commit descriptivo.
4. Sube tus cambios a tu repositorio bifurcado.
5. Abre un pull request al repositorio principal.

LICENCIA

El proyecto está licenciado bajo la Apache License 2.0. Consulta el archivo LICENSE para obtener más detalles.