K8s Warning Monitor MCP

<div align="center"> <h1>🚨 K8s Warning Monitor MCP</h1> <p><b>A custom Model Context Protocol (MCP) server for intelligent Kubernetes cluster diagnostics.</b></p>

</div>

---

📖 Overview

The K8s Warning Monitor is a purpose-built Model Context Protocol (MCP) server that acts as a targeted diagnostic bridge between your local Kubernetes cluster (like Minikube) and AI coding assistants (like Cline or Roo Code).

Instead of flooding the AI's context window with thousands of normal cluster scheduling events, this tool strictly filters for Warning or Failed events. It parses the data into clean, formatted text, allowing your AI to instantly understand what is currently broken in your environment without wasting tokens.

✨ Features

• 🎯 Context-Optimized: Only returns actionable warnings (e.g., ImagePullBackOff, CrashLoopBackOff, FailedScheduling).
• 🐳 Fully Dockerized: Runs ephemerally as an interactive Docker container.
• 🪟 Windows 11 & Minikube Friendly: Includes the exact configuration needed to route container traffic back to a Windows host's Minikube cluster via host.docker.internal.
• ⚡ Automated Lifecycle: The AI spins the container up to execute the tool, communicates via standard streams (stdio), and the --rm flag cleans it up immediately after.

---

🛠️ Prerequisites

Before you begin, ensure you have the following installed on your machine:

• Docker Desktop (running)
• Minikube (or any local/remote Kubernetes cluster)
• kubectl configured and authenticated
• VS Code with the Cline (or equivalent MCP-compatible) extension

---

🚀 Setup & Installation

1. Clone the Repository

git clone https://github.com/your-username/k8s-warning-monitor.git
cd k8s-warning-monitor

2. Build the Docker Image

Build the lightweight Node.js Alpine container:

docker build -t mcp-k8s-warnings .

3. Prepare the Docker-Friendly Kubeconfig

Because Docker containers have their own isolated network loopback, we need to create a flattened kubeconfig that allows the container to talk to your host's Minikube.

Generate the flattened config (embeds certificates directly):

kubectl config view --raw --minify --flatten > kubeconfig-docker

⚠️ CRITICAL MINIKUBE FIX: Open kubeconfig-docker in your editor. Locate the server: address (it usually points to https://127.0.0.1:<port>). Change 127.0.0.1 to host.docker.internal.

Example:

# Change this:
server: https://127.0.0.1:58253
# To this:
server: https://host.docker.internal:58253

4. Connect to Cline (VS Code)

Open your MCP settings in VS Code (cline_mcp_settings.json) and add the server configuration.

Note: Update the D:\study\... volume path to match your absolute clone directory.

{
  "mcpServers": {
    "warning-monitor-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "D:\path\to\your\clone\k8s-warning-monitor\kubeconfig-docker:/root/.kube/config:ro",
        "mcp-k8s-warnings"
      ]
    }
  }
}

---

🤖 Usage Examples

Once configured, reload your VS Code window. Open your AI chat interface and try the following prompts:

🗣️ "Using the warning-monitor-docker tool, get my cluster errors."

🗣️ "Check if there are any failing pods in the cluster, then suggest a fix for the highest priority warning."

🗣️ "Run a cluster health check using the warning monitor tool."

---

🔒 Security & Architecture Note

Is this safe to run? The TypeScript code executing inside this container is strictly read-only. It only utilizes the @kubernetes/client-node API to perform listEventForAllNamespaces() requests. The AI has no programmed capability to modify, delete, or create resources through this specific MCP server.

However, the container itself inherits your privileges. Because the installation mounts your local, flattened kubeconfig-docker file into the container, the Docker process has the same cluster administrative rights as your local user. For strict enterprise security, you should replace the flattened config with one utilizing a restricted Kubernetes ServiceAccount bound to a ClusterRole that only permits "get, list, watch" verbs.