mcp-k8s-observability

Servidor MCP en Python que conecta agentes de IA (Claude Desktop, Cursor, etc.) con la infraestructura de Kubernetes y el stack de observabilidad.

La idea es simple: en vez de copiar y pegar outputs de kubectl y curl en el chat, el agente puede llamar directamente a las herramientas y obtener el estado de los pods, hacer queries a Prometheus y buscar logs en Loki.

Que hace

El servidor expone 10 herramientas via JSON-RPC (transporte stdio):

Kubernetes

• list_namespaces - Lista namespaces con estado y fecha de creacion

• get_kubernetes_pods - Pods con su estado, reinicios y nodo asignado

• get_pod_detail - Detalle profundo del pod: contenedores, imagenes, exit codes, limits/requests de CPU/memoria y condiciones

• get_cluster_nodes - Nodos del cluster con su estado (Ready/NotReady), roles, capacidad y condiciones de presion

• get_cluster_events - Eventos del cluster (BackOff, OOMKilled, FailedScheduling)

• get_pod_logs - Ultimas N lineas de log via la API de K8s (kubectl logs --tail), con soporte --previous

Observabilidad

• query_prometheus_metrics - PromQL instant query

• query_prometheus_range - PromQL range query con ventana y resolucion configurable

• query_loki_logs - LogQL contra Grafana Loki

Diagnostico

• diagnose_pod_health - Correlacion automatica: estado del pod + exit codes + metricas + eventos + logs (actuales y de la instancia previa al crash) con health score (0-100) y acciones sugeridas

Related MCP server: OpenTelemetry MCP Server

Modo mock

Todo funciona sin cluster real. Con MCP_MODE=mock genera datos sinteticos que simulan pods en CrashLoopBackOff, OOMKilled, etc. Incluye logs mock realistas (stack traces de Java OOM, latencias de transacciones, probes de health check). Util para probar prompts y ver como reacciona el agente sin necesidad de tener infraestructura activa.

Como probarlo

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

# Con make
make setup
make test

# O manual
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python test_client.py

La salida muestra el handshake MCP, la lista de herramientas, pods, logs del pod anterior y un diagnostico automatico de un pod simulado con OOMKilled.

Conectar con Claude Desktop

Agregar en claude_desktop_config.json:

{
  "mcpServers": {
    "k8s-observability": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/ruta/a/mcp-k8s-observability",
      "env": { "MCP_MODE": "mock" }
    }
  }
}

Estructura

src/
  config.py              # Variables de entorno y settings
  models.py              # Esquemas Pydantic
  server.py              # Loop stdio + despachador JSON-RPC
  tools/
    k8s_tools.py         # Pods, eventos, namespaces y logs (live o mock)
    prometheus_tools.py  # Queries PromQL (instant y range)
    loki_tools.py        # Queries LogQL
test_client.py           # Prueba rapida sin cliente externo
Makefile                 # setup, test, lint, docker-build
Dockerfile               # Multi-stage, 70MB aprox

Por que existe esto

En el trabajo uso herramientas similares para no tener que estar saltando entre terminales, Grafana y Slack cuando llega una alerta. Este repo es una version limpia de esa idea, sin datos corporativos, que cualquiera puede clonar y adaptar.

Licencia

MIT