MCP K8s Context Server

Un servidor FastMCP que expone Kubernetes como un conjunto de herramientas de solo lectura consumibles por LLMs, más una capa de análisis para el análisis de salud de pods y el seguimiento de tendencias de recursos.

Características

Related MCP server: Kube MCP

Estructura del Proyecto

mcp-k8s-context-server/
├── k8s_mcp_server.py        # FastMCP server (all tools)
├── requirements.txt         # Python dependencies
├── Dockerfile               # Container image definition
├── k8s/
│   ├── serviceaccount.yaml  # ServiceAccount + Namespace
│   ├── role.yaml            # Least-privilege ClusterRole (read-only)
│   ├── rolebinding.yaml     # ClusterRoleBinding
│   └── deployment.yaml      # Deployment + Service
└── .github/
    └── workflows/
        └── ci.yml           # Build + kubeconform validation

Desarrollo Local

# Create and activate a virtual environment
python -m venv .venv && source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run with local kubeconfig (falls back automatically from in-cluster config)
python k8s_mcp_server.py

Despliegue en el Clúster (minikube)

Prerrequisitos

# Install minikube, kubectl, docker
minikube version   # >= 1.32
kubectl version    # >= 1.28
docker version     # >= 24

Paso 1 — Iniciar minikube

minikube start --cpus=2 --memory=4096

Paso 2 — Habilitar metrics-server (necesario para get_resource_trends)

minikube addons enable metrics-server

Paso 3 — Construir y cargar la imagen en minikube

# Build locally
docker build -t mcp-k8s-server:latest .

# Load into minikube's image registry (no registry push needed)
minikube image load mcp-k8s-server:latest

# Verify the image is available
minikube image ls | grep mcp-k8s-server

Paso 4 — Aplicar los manifiestos de Kubernetes

# Apply in dependency order: SA → Role → Binding → Deployment
kubectl apply -f k8s/serviceaccount.yaml
kubectl apply -f k8s/role.yaml
kubectl apply -f k8s/rolebinding.yaml
kubectl apply -f k8s/deployment.yaml

Paso 5 — Verificar que el Pod está en ejecución

kubectl get pods -n mcp-system
# Expected:
# NAME                              READY   STATUS    RESTARTS   AGE
# mcp-k8s-server-xxxxxxxxx-xxxxx   1/1     Running   0          30s

kubectl logs -n mcp-system deploy/mcp-k8s-server
# Expected: "Using in-cluster Kubernetes config (ServiceAccount token)"

Paso 6 — Probar las herramientas de solo lectura en el clúster

# Port-forward to access the server from your laptop
kubectl port-forward -n mcp-system svc/mcp-k8s-server 8000:8000 &

# Create a test pod to query
kubectl run nginx-test --image=nginx --restart=Never

# Test list_pods
curl -s http://localhost:8000/tools/list_pods \
  -H 'Content-Type: application/json' \
  -d '{"namespace":"default"}' | jq .

# Test get_pod_logs
curl -s http://localhost:8000/tools/get_pod_logs \
  -H 'Content-Type: application/json' \
  -d '{"pod_name":"nginx-test","namespace":"default","tail_lines":20}' | jq .

# Test analyze_pod_health
curl -s http://localhost:8000/tools/analyze_pod_health \
  -H 'Content-Type: application/json' \
  -d '{"namespace":"default","hours":1}' | jq .

Paso 7 — Demostrar que RBAC bloquea las operaciones de escritura

La ServiceAccount no tiene verbos de escritura. Para confirmarlo:

# Exec into the pod and try to delete another pod using the SA token
MCP_POD=$(kubectl get pod -n mcp-system -l app=mcp-k8s-server -o jsonpath='{.items[0].metadata.name}')

kubectl exec -n mcp-system $MCP_POD -- \
  kubectl delete pod nginx-test --namespace=default \
  --token=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) \
  --server=https://kubernetes.default.svc \
  --certificate-authority=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

Salida esperada:

Error from server (Forbidden): pods "nginx-test" is forbidden:
  User "system:serviceaccount:mcp-system:mcp-server-sa" cannot delete
  resource "pods" in API group "" in the namespace "default"

Esta respuesta 403 Forbidden del servidor de la API es la prueba en vivo de que el alcance de RBAC funciona — la ServiceAccount puede leer pero no puede modificar ningún recurso.

Diseño de Mínimos Privilegios RBAC

Filosofía

Concede solo lo necesario, deniega explícitamente todo lo demás.

El servidor MCP es una herramienta de observabilidad — lee el estado del clúster para ayudar a operadores y sistemas de IA a entender lo que está sucediendo. No tiene ninguna razón legítima para crear, modificar o eliminar ningún recurso.

Lo que se concede

Lo que explícitamente NO se concede

Esto significa que un servidor MCP comprometido no puede eliminar pods, escalar deployments a cero, modificar secretos ni afectar ninguna carga de trabajo en ejecución. El radio de explosión de un servidor MCP comprometido se limita a leer información, no a interrumpirla.

Capa de Análisis

analyze_pod_health

1. Lista todos los pods en el namespace.

2. Obtiene hasta 500 líneas de log por pod.

3. Compara patrones con un catálogo de indicadores de fallo conocidos:

   • OOMKilled, CrashLoopBackOff

   • Excepciones de Python/Java (Traceback, RuntimeError, etc.)

   • Panic, SIGSEGV/SIGKILL, Errores de conexión, Permiso denegado

   • Fallos de sondas de Liveness/Readiness

4. Calcula una puntuación de salud por pod (menor = peor).

5. Devuelve los pods clasificados del peor al mejor con recuentos de frecuencia de errores.

6. Persiste los resultados en SQLite para análisis histórico.

get_resource_trends

1. Resuelve el selector de pods desde la especificación del Deployment.

2. Lee los límites de recursos desde las especificaciones del pod.

3. Consulta la API de Métricas de Kubernetes (metrics.k8s.io/v1beta1) para CPU/memoria en vivo.

4. Calcula: promedio, pico y % del límite tanto para CPU como para memoria.

5. Persiste cada instantánea en mcp_analytics.db para que las tendencias se acumulen entre llamadas.

Requiere el addon metrics-server: minikube addons enable metrics-server

CI / Integración Continua

El flujo de trabajo de GitHub Actions (.github/workflows/ci.yml) se ejecuta en cada push y PR:

1. Docker Build — construye la imagen sin subirla (valida el Dockerfile + dependencias).

2. kubeconform — valida todos los manifiestos k8s/*.yaml contra el esquema de Kubernetes 1.29 en modo estricto.

3. ruff — analiza k8s_mcp_server.py en busca de errores de Python y estilo.

Variables de Entorno

Licencia

MIT