K8s MCP Server

Un servidor para herramientas CLI de Kubernetes como kubectl, istioctl, helm y argocd, que admite la gestión de múltiples clústeres mediante kubeconfig dinámico.

GitHub
5
Prueba este MCPPatrocinado

Documentación

Servidor MCP de K8s

CI 状态 发布状态 codecov 镜像标签 镜像大小 Python 版本 许可证: MIT

Este proyecto se basa en el excelente trabajo de alexei-led/k8s-mcp-server. ¡Agradecemos sinceramente al autor original!

El Servidor MCP de K8s es un servicio accesible por red construido sobre fastapi-mcp. Permite que modelos de lenguaje grandes (LLM) como Claude ejecuten de forma segura herramientas CLI de Kubernetes (kubectl, istioctl, helm, argocd). Se ofrece a través del protocolo estándar de control de modelos (MCP) y admite el paso dinámico de kubeconfig en cada solicitud, lo que permite una gestión fluida de múltiples clústeres de Kubernetes.

Características principales

  • Implementación estándar de MCP: Utiliza fastapi-mcp para exponer automáticamente los endpoints de FastAPI como herramientas MCP, sin necesidad de implementar el protocolo manualmente.
  • Soporte dinámico de múltiples clústeres: El contenido de kubeconfig se pasa directamente en cada solicitud de API en formato codificado en Base64, sin necesidad de configuración previa ni montaje de archivos.
  • Endpoints de herramientas independientes: Cada herramienta CLI (kubectl, helm, etc.) tiene su propio endpoint HTTP dedicado, con una estructura clara.
  • Servicio independiente: Puede ejecutarse como un contenedor Docker independiente o dentro de Kubernetes.
  • Documentación OpenAPI automática: Hereda las ventajas de FastAPI, generando y proporcionando automáticamente documentación interactiva de API (a través de /docs).

Cómo funciona

graph TD
    subgraph "客户端"
        A["用户 / LLM"]
    end
    
    subgraph "K8s MCP 服务器"
        B["MCP 端点 (/mcp)"]
        C["工具端点"]
        D["执行引擎"]
    end

    subgraph "目标环境"
        E["目标 Kubernetes 集群"]
    end

    A -->|"MCP 客户端连接到 /mcp"| B;
    B -->|"发现可用工具"| A;
    A -->|"发起工具调用请求"| C;
    C -->|"调用执行引擎"| D;
    D -->|"创建临时 kubeconfig 并执行命令"| E;
    E -->|"返回结果"| D;
    D -->|"返回 CommandResponse"| C;
    C -->|"将结果通过 MCP 返回"| A;

Inicio rápido

1. Ejecutar el Servidor MCP de K8s

Inicie el servidor rápidamente en local usando Docker:

docker run -d --rm -p 9096:9096 --name mcp-server \
  docker.io/apecloud/k8s-mcp-server:latest

El servidor ahora se está ejecutando en http://localhost:9096. Puede visitar http://localhost:9096/docs para ver todas las herramientas disponibles y su documentación de API.

2. Configurar en el cliente MCP

Para cualquier cliente compatible con MCP (como mcphost, Cursor, Claude Desktop, etc.), agregue la siguiente configuración:

{
  "mcpServers": {
    "kubernetes": {
      "url": "http://localhost:9096/mcp"
    }
  }
}

Reemplace localhost con la dirección IP del host donde se ejecuta k8s-mcp-server (si no está en la misma máquina).

3. Comenzar a usar

Una vez iniciado su cliente MCP, este descubrirá automáticamente las herramientas proporcionadas por el Servidor MCP de K8s. Ahora puede comenzar a dar instrucciones.

  • "Usando la herramienta kubectl, ejecute el comando get pods -n default."
  • "Ayúdeme a verificar el estado de nginx-deployment en el espacio de nombres prod."

Desarrollo y ejecución local

1. Ejecutar el Servidor MCP de K8s

Puede usar el comando quick-start en Makefile para iniciar el servidor rápidamente en local:

make quick-start

Esto construirá la imagen Docker y ejecutará el contenedor en local; el servidor se ejecutará en http://localhost:9096.

2. Verificar el estado del servidor

Una vez que el servidor esté en marcha, puede verificar su estado de salud con el siguiente comando curl:

curl http://localhost:9096/health

Si el servidor funciona correctamente, recibirá una respuesta exitosa.

Ejecutar desde el código fuente

Si desea ejecutar el Servidor MCP de K8s desde el código fuente, siga estos pasos:

1. Clonar el repositorio

Si aún no ha clonado el repositorio de este proyecto, hágalo primero:

git clone https://github.com/apecloud/mcp-k8s.git
cd mcp-k8s

2. Crear y activar un entorno virtual

Se recomienda usar un entorno virtual para gestionar las dependencias del proyecto:

python3 -m venv .venv
source .venv/bin/activate

3. Instalar dependencias

Instale todas las dependencias necesarias para el proyecto:

pip install .

4. Ejecutar el servidor

Use uvicorn para iniciar la aplicación FastAPI:

uvicorn src.k8s_mcp_server.app:app --host 0.0.0.0 --port 9096

5. Verificar el estado del servidor

Después de iniciar el servidor, puede verificar su estado de salud con el siguiente comando curl:

curl http://localhost:9096/health

Si el servidor funciona correctamente, recibirá una respuesta exitosa.

Ejemplo de uso de API (Curl)

Puede interactuar directamente con los endpoints de herramientas del servidor mediante curl.

Método de autenticación con Kubeconfig

La información de kubeconfig se puede proporcionar de dos maneras principales:

  1. Mediante cabecera HTTP (X-Kubeconfig):

    • Coloque el contenido de kubeconfig codificado en Base64 en la cabecera X-Kubeconfig.
    • Esta forma puede ahorrar consumo de tokens para los modelos de lenguaje, porque kubeconfig no se cuenta como parte del cuerpo de la solicitud en la entrada del modelo.

  2. Mediante el cuerpo de la solicitud (campo kubeconfig):

    • Coloque el contenido de kubeconfig codificado en Base64 como valor del campo kubeconfig en el cuerpo JSON de la solicitud.

Ejemplo:

  1. Codifique su contenido de kubeconfig en Base64:

    # macOS
KUBECONFIG_B64=$(cat ~/.kube/config | base64)

# Linux
KUBECONFIG_B64=$(cat ~/.kube/config | base64 -w 0)

  2. Envíe la solicitud mediante la cabecera de la solicitud (X-Kubeconfig):

    curl -X POST http://localhost:9096/tools/kubectl \
  -H "Content-Type: application/json" \
  -H "X-Kubeconfig: $KUBECONFIG_B64" \
  -d @- << EOF
{
  "command": "get pods -n default"
}
EOF

  3. Envíe la solicitud mediante el cuerpo de la solicitud:

    curl -X POST http://localhost:9096/tools/kubectl \
  -H "Content-Type: application/json" \
  -d @- << EOF
{
  "command": "get pods -n default",
  "kubeconfig": "$KUBECONFIG_B64"
}
EOF

    Recibirá una respuesta JSON que contiene el resultado de la ejecución del comando.

Características funcionales

  • Múltiples herramientas de Kubernetes: kubectl, helm, istioctl y argocd.
  • Soporte nativo de proveedores de nube: Dado que kubeconfig se pasa dinámicamente, se admite de forma nativa cualquier clúster de Kubernetes que cumpla con el estándar, incluidos AWS EKS, Google GKE y Azure AKS.
  • Seguridad: Se ejecuta en el contenedor como usuario no root.
  • Configuración sencilla: Configuración simple mediante variables de entorno.

Documentación

  • Documentación de API: Después de iniciar el servidor, visite la ruta /docs para obtener la documentación interactiva completa de la API.
  • Documentación de fastapi-mcp: https://github.com/tadata-org/fastapi_mcp

Contribuciones

¡Agradecemos las contribuciones de la comunidad! No dude en enviar problemas y solicitudes de extracción.