🛡️ kube-sentinel-mcp

Autonomous Kubernetes SRE & Incident Diagnosis Engine powered by Model Context Protocol (MCP)

Real-time Kubernetes incident triage, automated Root Cause Analysis (RCA), and GitOps-ready remediation patches with safety guardrails.

Key Features • Architecture • Quickstart • Claude Desktop / MCP Setup • CLI Usage • Simulation Mode • Helm Deployment

📌 Overview

kube-sentinel-mcp bridges AI Agents (Claude, Antigravity, Bedrock, Cursor) and Kubernetes clusters via the open Model Context Protocol (MCP).

When pods enter CrashLoopBackOff, OOMKilled, ImagePullBackOff, or fail probes:

1. Telemetry Correlation: Pulls container exit codes, previous crash logs, cgroup memory peaks, and Kubernetes warning events.

2. Automated Root Cause Analysis (RCA): Synthesizes evidence to classify the incident and score confidence.

3. Guardrail-Protected Remediation: Generates a unified GitOps YAML diff and kubectl patch command while enforcing blast-radius checks (preventing unintended writes to kube-system).

4. Zero-Cluster Simulation: Includes pre-packaged offline incident scenarios so developers and SREs can evaluate the agent without requiring a live cloud cluster.

Related MCP server: K8gentS

🏛️ Architecture

flowchart TD
    subgraph ClientLayer["AI Agents & SRE Interfaces"]
        Claude["Claude Desktop / Cursor / Antigravity"]
        CLI["kube-sentinel CLI"]
        Prom["Prometheus Alertmanager Webhook"]
    end

    subgraph SentinelCore["kube-sentinel-mcp Engine"]
        MCPServer["MCP Server (JSON-RPC stdio / SSE)"]
        Analyzer["Incident Analyzer & Correlation Engine"]
        RCA["RCA Heuristic Engine (OOM, CrashLoop, Probes)"]
        Remediator["Remediation Engine & Safety Guardrails"]
        ClientSwitch{"Live Cluster Reachable?"}
    end

    subgraph DataPlane["Kubernetes Target"]
        LiveK8s["Live K8s API (In-Cluster SA / Kubeconfig)"]
        Simulator["In-Memory Incident Simulator (Offline Scenarios)"]
    end

    ClientLayer --> MCPServer
    CLI --> Analyzer
    Prom --> Analyzer
    MCPServer --> Analyzer
    Analyzer --> ClientSwitch
    ClientSwitch -- Yes --> LiveK8s
    ClientSwitch -- No / Simulate --> Simulator
    Analyzer --> RCA
    RCA --> Remediator
    Remediator -->|"Unified YAML Diff & Kubectl Command"| ClientLayer

✨ Key Features

• Standard MCP Protocol: Exposes 7 tools (k8s_scan_incidents, k8s_get_pod_diagnostics, k8s_get_resource_metrics, k8s_run_rca, k8s_generate_remediation, k8s_list_simulations, k8s_simulate_scenario).

• Deep Incident Diagnostics: Distinguishes between cgroup Linux OOMKiller (Exit 137), missing ConfigMap/Secret environment variables (Exit 1), image pull tag typos, and probe port mismatches.

• GitOps-Ready Remediation: Produces clean unified YAML diffs ready for automated Git pull requests (ArgoCD / Flux) or instant CLI hotfixes.

• Safety Guardrails: Blocks automated remediation on critical system namespaces (kube-system, kube-public, cert-manager) and verifies replica redundancy before rolling restarts.

• Alertmanager Webhook: Direct endpoint to consume firing Prometheus alerts and generate instant triage summaries.

• Zero External Dependencies Required for Demo: Bundles full offline scenarios.

🚀 Quickstart

1. Installation

git clone https://github.com/ekrmcakir/kube-sentinel-mcp.git
cd kube-sentinel-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install -e ".[dev]"

2. Verify Installation

kube-sentinel version

🖥️ CLI Usage

Scan Cluster for Incidents

Scan an active cluster (or use --simulate for offline mode):

kube-sentinel scan --simulate

Output:

              Active Incidents & Unhealthy Workloads (4 detected)               
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Pod Name     ┃ Namespace  ┃ Phase   ┃ Owner        ┃ Restarts ┃ Primary      ┃
┃              ┃            ┃         ┃              ┃          ┃ Reason       ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ auth-service │ auth       │ Running │ Deployment/… │       12 │ CrashLoop…   │
│ cart-service │ ecommerce  │ Pending │ Deployment/… │        0 │ ImagePull…   │
│ payment-api  │ production │ Running │ Deployment/… │        8 │ OOMKilled    │
│ orders-api   │ production │ Running │ Deployment/… │        6 │ Not Ready    │
└──────────────┴────────────┴─────────┴──────────────┴──────────┴──────────────┘

Run Root Cause Analysis (RCA) & Remediation

kube-sentinel diagnose --pod payment-api-7b8f94cb4d-x92zk --simulate

Rich Terminal Output displays:

• RCA Severity & Category (CRITICAL, OOM_KILLED, 98% confidence)

• Corroborated Telemetry (Linux cgroup peak memory: 256MB / 256MB, exit code 137, event details)

• Safety Guardrail Audit (PASSED - Non-system workload namespace)

• Unified YAML Diff (doubling memory requests & limits)

• Ready-to-run kubectl command

🖥️ SRE War-Room Web UI Dashboard

Launch the reactive, dark-mode SRE dashboard right in your browser:

kube-sentinel ui --port 8080 --simulate

Open http://localhost:8080 to inspect live anomaly feeds, memory utilization gauges, and apply 1-click GitOps patches.

🤖 Claude Desktop / MCP Setup

Integrate Sentinel directly into your Claude Desktop, Cursor, or Antigravity agents.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kube-sentinel": {
      "command": "/path/to/kube-sentinel-mcp/.venv/bin/kube-sentinel",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Or run as a remote SSE service on a cluster:

kube-sentinel serve --transport sse --port 8000

🧪 Zero-Cluster Simulation Mode

Evaluate all RCA rules without needing access to a real Kubernetes cluster:

# List available mock incident scenarios
kube-sentinel simulate

# Trigger OOMKilled scenario
kube-sentinel simulate --scenario oom-crash-payment

# Trigger missing environment variable crash loop
kube-sentinel simulate --scenario crashloop-missing-env

# Trigger image tag typo scenario
kube-sentinel simulate --scenario imagepull-typo-tag

📦 Helm Chart Deployment

Deploy Sentinel in-cluster with read-only cluster role permissions:

helm upgrade --install kube-sentinel ./helm/kube-sentinel-mcp \
  --namespace kube-system \
  --set replicaCount=1

🧪 Running Tests

pytest tests -v

All 10 unit and integration tests validate MCP tool definitions, RCA classifiers, safety guardrails, and Alertmanager ingestion.

📄 License

Distributed under the MIT License. Copyright (c) 2026 Ekrem Cakir.