Servidor MCP Kubernetes

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

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

Uso con Claude Desktop

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

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

El servidor se conectará automáticamente a su contexto kubectl actual. Asegúrese de que tiene

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

Puede verificar su conexión pidiendo a Claude que liste sus pods o que cree un despliegue de prueba.

Si tiene errores abra un terminal estándar y ejecute kubectl get pods para ver si puede conectarse a su cluster sin problemas de credenciales.

Uso con mcp-chat

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

npx mcp-chat --servidor "npx mcp-servidor-kubernetes"

Alternativamente, pásele su archivo de configuración de Claude Desktop existente de arriba (Linux debe pasar la ruta correcta a 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

• Conexión a un clúster Kubernetes
• API kubectl unificada para la gestión de 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 logs con kubectl_logs
  • Gestionar contextos kubectl con kubectl_context
  • Explicar los recursos de Kubernetes con explain_resource
  • Listar recursos API con list_api_resources
  • Escalar recursos con kubectl_scale
  • Actualizar campos de un recurso con kubectl_patch
  • Gestionar despliegues con kubectl_rollout
  • Ejecutar cualquier comando kubectl con kubectl_generic
  • Verificar la conexión con ping
• Operaciones avanzadas
  • Escalar despliegues con kubectl_scale (sustituye a scale_deployment)
  • Port forward a pods y servicios con port_forward
  • Ejecutar operaciones Helm
    • Instalar, actualizar y desinstalar gráficos
    • Soporte para valores personalizados, repositorios y versiones
• Aviso 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 espacio de nombres opcional.
• Modo no destructivo para leer y crear/actualizar sólo el acceso a los clusters

Avisos

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

mensaje k8s-diagnose

Este indicador proporciona un flujo sistemático de solución de problemas para los pods de Kubernetes. Acepta una palabra clave para identificar los pods relevantes y un espacio de nombres opcional para restringir la búsqueda. El resultado de la consulta le guiará a través de un flujo autónomo de resolución de problemas, proporcionándole instrucciones para identificar problemas, recopilar pruebas y sugerir pasos para solucionarlos.

Desarrollo local

Asegúrese de tener instalado bun. 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. Inicie el servidor en modo de desarrollo (vigila los cambios en los archivos):

bun run dev

2. Ejecutar pruebas unitarias:

bun run test

3. Construir el proyecto:

bun run build

4. Pruebas locales con Inspector

npx @modelcontextprotocol/inspector node dist/index.js # Siga las instrucciones en el terminal para el enlace Inspector

5. Pruebas locales con Claude Desktop

{ "mcpServers": { "mcp-server-kubernetes": { "command": "node", "args": ["/ruta/su/servidor mcp-kubernetes/dist/index.js"] } }

6. Pruebas locales con mcp-chat

bun ejecutar chat

Contribución

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

Avanzado

Modo no destructivo

Puede ejecutar el servidor en un modo no destructivo que deshabilita todas las operaciones destructivas (eliminar pods, eliminar despliegues, eliminar espacios de nombres, 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 sólo lectura y de creación/actualización de recursos siguen estando 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 Helm: install_helm_chart, upgrade_helm_chart
• Conectividad: port_forward, stop_port_forward
• Gestión de contexto: kubectl_context

Comandos desactivados en modo no destructivo

Las siguientes operaciones destructivas están deshabilitadas:

• kubectl_delete: Eliminación de cualquier recurso de Kubernetes
• uninstall_helm_chart: Desinstalación de gráficos de Helm
• cleanup: Limpieza de recursos gestionados
• kubectl_generic: Acceso general a comandos kubectl (puede incluir operaciones destructivas)

Para funciones avanzadas adicionales, consulte el ADVANCED_README.md.

Arquitectura

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

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

Flujo de Peticiones

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

sequenceDiagram participante Client participante Transport como Transport Layer participante Server como MCP Server participante Filter como Tool Filter participante Handler como Request Handler participante K8sManager como KubernetesManager participante K8s como Kubernetes API Nota sobre Transport: StdioTransport o<br>SSE Transport Cliente->>Transporte: Send Request Transport->>Server: Forward Request alt Tools Request Server->>Filter: Filtrar herramientas disponibles Nota sobre Filtro: Eliminar herramientas destructivas<br>si está en modo no destructivo Filter->>Handler: Route to tools handler alt kubectl operations Handler->>K8sManager: Ejecutar operación kubectl K8sManager->>K8s: Make API call else Helm operations Handler->>K8sManager: Ejecutar operación Helm K8sManager->>K8s: Make API call else Port Forward operations Handler->>K8sManager: Configurar reenvío de puertos K8sManager->>K8s: Hacer llamada API fin K8s-->>K8sManager: Devuelve resultado K8sManager-->>Handler: Procesar respuesta Handler-->>Servidor: Devuelve el resultado de la herramienta si no Solicitud de recursos Servidor->>Handler: Route to resource handler Handler->>K8sManager: Obtener datos de recursos K8sManager->>K8s: Consulta API K8s-->>K8sManager: Devuelve datos K8sManager-->>Handler: Formatear respuesta Handler-->>Servidor: Devuelve datos del recurso final Servidor-->>Transporte: Enviar respuesta Transporte-->>Cliente: Devolver respuesta final

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

Publicar una nueva versión

Vaya a la página de versiones, haga clic en "Draft New Release", haga clic en "Choose a tag" y cree una nueva etiqueta escribiendo un nuevo número de versión utilizando el formato semver "v{major}.{minor}.{patch}". A continuación, escriba el título de la versión "Versión v{mayor}.{menor}.{parche}" y una descripción / registro de cambios si es necesario y haga clic en "Publicar versión".

Se creará una nueva etiqueta que activará la creación de una nueva versión a través del flujo de trabajo cd.yml. Una vez hecho esto, la nueva versión se publicará en npm. Tenga en cuenta que no hay necesidad de actualizar la versión package.json manualmente, 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

Añadir clusters a kubectx.

Historia de Star

🖊️ Citar

Si encuentra útil este repositorio, por favor cite:

@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} }