MCP Kubernetes Pods

Servidor MCP para OpenCode que permite consultar pods/deployments y ejecutar operaciones controladas sobre deployments de Kubernetes.

Capacidades

• Listar pods y deployments.
• Consultar estado detallado de pods.
• Resolver pod -> ReplicaSet -> Deployment.
• Leer variables de entorno configuradas en deployments.
• Reiniciar deployments mediante patch del pod template.
• Crear o actualizar variables de entorno en deployments permitidos.

Seguridad

Este MCP no expone herramientas para eliminar recursos, ejecutar comandos dentro de pods, aplicar manifests arbitrarios, escalar deployments, crear recursos de infraestructura ni modificar configuraciones globales del cluster.

La seguridad real debe reforzarse con RBAC de Kubernetes. Usa permisos minimos: get, list, watch sobre pods/deployments/replicasets y patch sobre deployments.

Las actualizaciones de variables solo funcionan si el deployment esta incluido en K8S_ALLOWED_ENV_DEPLOYMENTS.

Requisitos

• Node.js 20 o superior.
• Acceso a un cluster Kubernetes mediante token o kubeconfig.
• Permisos RBAC suficientes para consultar recursos y parchear deployments.

Uso con NPX

Una vez publicado en npm:

npx -y @munlib/mcp-kubernetes-pods

Instalacion Local

npm install
npm run build
npm start

Configuracion

Token

K8S_TOKEN=eyJhbGciOiJSUzI1NiIs...
K8S_API_SERVER=https://kubernetes.default.svc
K8S_SKIP_TLS_VERIFY=false
K8S_DEFAULT_NAMESPACE=apis
K8S_ALLOWED_NAMESPACES=apis
K8S_LOCAL_RBAC_POLICY_FILE=C:\ruta\MCP_KUBERNETES\k8s\rbac.yaml
K8S_LOCAL_RBAC_POLICY_NAMESPACES=apis
K8S_ALLOWED_ENV_DEPLOYMENTS=srv-cron-tarifas

Kubeconfig

KUBECONFIG=C:\Users\tu_usuario\.kube\config
K8S_CONTEXT=minikube
K8S_DEFAULT_NAMESPACE=default
K8S_ALLOWED_NAMESPACES=default,staging
K8S_LOCAL_RBAC_POLICY_FILE=C:\ruta\MCP_KUBERNETES\k8s\rbac.yaml
K8S_LOCAL_RBAC_POLICY_NAMESPACES=default,staging
K8S_ALLOWED_ENV_DEPLOYMENTS=api,worker

Si usas KUBECONFIG, no necesitas definir K8S_TOKEN, K8S_API_SERVER, K8S_CA_FILE ni K8S_SKIP_TLS_VERIFY.

Variables

| Variable | Requerido | Default | Descripcion | |---|---|---|---| | K8S_TOKEN | No* | - | Token del ServiceAccount. Requerido si no usas kubeconfig. | | K8S_API_SERVER | No | https://localhost:6443 | URL del API de Kubernetes. | | K8S_SKIP_TLS_VERIFY | No | false | Omite verificacion TLS. | | K8S_CA_FILE | No | - | Ruta al certificado CA del cluster. | | KUBECONFIG | No* | - | Ruta al archivo kubeconfig. Requerido si no usas token. | | K8S_CONTEXT | No | - | Contexto especifico del kubeconfig. | | K8S_DEFAULT_NAMESPACE | No | default | Namespace por defecto. | | K8S_ALLOWED_NAMESPACES | No | - | Namespaces permitidos, separados por coma. | | K8S_LOCAL_RBAC_POLICY_FILE | Si para acciones Kubernetes | - | Ruta local a un manifiesto RBAC usado como politica local deny-by-default dentro del MCP. | | K8S_LOCAL_RBAC_POLICY_NAMESPACES | No | - | Namespaces donde se aplican localmente las reglas del Role; si no se define, se usa metadata.namespace del YAML. | | K8S_ALLOWED_ENV_DEPLOYMENTS | Si para actualizar env | - | Deployments permitidos para actualizar variables, separados por coma. |

Si K8S_ALLOWED_NAMESPACES esta definido, el MCP rechaza namespaces fuera de esa lista antes de llamar al API de Kubernetes.

Si K8S_ALLOWED_ENV_DEPLOYMENTS no esta definido, el MCP bloquea todas las actualizaciones de variables de entorno.

El MCP requiere K8S_LOCAL_RBAC_POLICY_FILE para ejecutar acciones contra Kubernetes. Si la variable no existe, el archivo no existe o el manifiesto no contiene un Role, deniega toda accion contra el cluster. Si K8S_LOCAL_RBAC_POLICY_NAMESPACES esta definido, las reglas del Role se aplican localmente a esos namespaces aunque el YAML tenga un metadata.namespace fijo.

OpenCode

Desde NPM

{
  "mcp": {
    "kubernetes_pods": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "@munlib/mcp-kubernetes-pods"],
      "environment": {
        "K8S_TOKEN": "eyJhbGciOiJSUzI1NiIs...",
        "K8S_API_SERVER": "https://kubernetes.docker.internal:6443",
        "K8S_SKIP_TLS_VERIFY": "true",
        "K8S_DEFAULT_NAMESPACE": "apis",
        "K8S_ALLOWED_NAMESPACES": "apis",
        "K8S_LOCAL_RBAC_POLICY_FILE": "C:/ruta/MCP_KUBERNETES/k8s/rbac.yaml",
        "K8S_LOCAL_RBAC_POLICY_NAMESPACES": "apis",
        "K8S_ALLOWED_ENV_DEPLOYMENTS": "srv-cron-tarifas"
      }
    }
  }
}

Build Local

{
  "mcp": {
    "kubernetes_pods": {
      "type": "local",
      "enabled": true,
      "command": ["node", "C:/ruta/MCP_KUBERNETES/dist/index.js"],
      "environment": {
        "KUBECONFIG": "C:/ruta/MCP_KUBERNETES/config/kubeconfig.portainer.yaml",
        "K8S_CONTEXT": "portainer-ctx-local",
        "K8S_DEFAULT_NAMESPACE": "apis",
        "K8S_ALLOWED_NAMESPACES": "apis",
        "K8S_LOCAL_RBAC_POLICY_FILE": "C:/ruta/MCP_KUBERNETES/k8s/rbac.yaml",
        "K8S_LOCAL_RBAC_POLICY_NAMESPACES": "apis",
        "K8S_ALLOWED_ENV_DEPLOYMENTS": "srv-cron-tarifas"
      }
    }
  }
}

Herramientas MCP

• list_allowed_namespaces: muestra namespaces permitidos por configuracion local.
• validate_effective_permissions: valida permisos efectivos de la credencial actual y alerta si puede eliminar pods en namespaces permitidos.
• list_pods: lista pods y estado resumido.
• get_pod_status: obtiene estado detallado de un pod.
• resolve_pod_workload: resuelve pod -> ReplicaSet -> Deployment.
• list_deployments: lista deployments y replicas.
• restart_deployment: reinicia pods de un deployment mediante annotation en el pod template.
• get_pod_env: muestra variables del deployment que administra un pod.
• get_deployment_env: muestra variables de entorno configuradas en un deployment.
• update_deployment_env: actualiza o crea una variable de entorno y dispara rollout.
• update_env_by_pod: actualiza una variable indicando un pod; el MCP resuelve el deployment y dispara rollout.

Publicacion en NPM

El paquete esta configurado como:

@munlib/mcp-kubernetes-pods

Antes de publicar, verifica que no existan tokens, kubeconfigs reales ni credenciales en archivos versionados.

Validar

npm run publish:check
npm run publish:dry-run

Publicar desde Windows

npm run publish:npm

Publicar desde Linux o macOS

npm run publish:npm:bash

Usar token de npm

$env:NPM_TOKEN = "npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
npm run publish:npm

export NPM_TOKEN="npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
npm run publish:npm:bash -- -- --bump none

Para primera publicacion selecciona none. Para actualizaciones usa patch, minor, major o prerelease.

Los scripts ejecutan build, typecheck, npm pack --dry-run y piden confirmacion antes de publicar.