kube-assistant-mcp

Agentic Kubernetes troubleshooting — as a CLI and as an MCP server.

kube-assistant-mcp connects a local LLM (via Ollama) or a hosted one (OpenAI-compatible) to your Kubernetes cluster. It scans for failing Pods (CrashLoopBackOff, OOMKilled, ImagePullBackOff, ...), correlates logs + events, explains the root cause in plain language, and proposes concrete, runnable fixes — or generates ready-to-use Deployment/Helm manifests.

It ships two ways to use it:

• CLI — kube-assistant scan / diagnose / fix / generate
• MCP server — the same capabilities exposed as tools for Cursor or Claude Desktop, so an AI agent can diagnose and (with your explicit confirmation) fix your cluster in natural language.

$ kube-assistant scan -n production
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
┃ Namespace  ┃ Pod          ┃ Issue            ┃ Restarts ┃ Severity ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
│ production │ api-7f8c9d   │ CrashLoopBackOff │ 14       │ critical │
│ production │ worker-2     │ OOMKilled        │ 3        │ high     │
└────────────┴──────────────┴──────────────────┴──────────┴──────────┘

Why

Debugging a failing Pod is a repetitive, mechanical loop: describe → logs --previous → get events → guess → fix. This tool automates the mechanical part and hands the LLM only the relevant, structured context it needs to actually help — instead of dumping a whole terminal session into a chat window.

Features

• Detection — classifies container states (waiting/terminated reasons) into known failure types with a severity score.
• Log analysis — regex-based pattern matching for common root causes (OOM, connection refused, DNS failure, missing env vars, permission errors, bad config, port conflicts, unhandled exceptions) — works even with the LLM turned off.
• LLM diagnosis — sends a compact, structured JSON payload (issue + log tail + recent events) to Ollama or an OpenAI-compatible endpoint and gets back a plain-language explanation plus a list of concrete fixes.
• Guarded auto-fix — every mutating action (pod restart, resource patch) is dry-run by default and requires an explicit confirm=True / --yes before it touches the cluster.
• Manifest generation — emits a Deployment+Service YAML pair, or a minimal, valid Helm chart skeleton.
• MCP server — built with FastMCP; drop it into Cursor or Claude Desktop and diagnose your cluster conversationally.

Installation

Option A — from PyPI

pip install kube-assistant-mcp
kube-assistant setup       # installs missing prerequisites (kubectl, Helm, Ollama + model) via Homebrew/official scripts
kube-assistant doctor      # verifies everything is ready

Option B — from source (one command)

git clone https://github.com/yonatani94/kube-assistant-mcp
cd kube-assistant-mcp
make setup                  # creates a venv, installs the Python package, runs the doctor check
source .venv/bin/activate
kube-assistant setup        # installs missing system tools (kubectl/Helm/Ollama) — different from `make setup` above

make setup bootstraps the Python side (venv + package). kube-assistant setup installs the system prerequisites the package needs to actually talk to a cluster and an LLM. Either way, kube-assistant doctor is the always-safe, read-only check: it verifies Python 3.10+, kubectl + cluster connectivity, and your configured LLM backend (Ollama or OpenAI), and tells you exactly what's missing. kube-assistant setup is the read-write counterpart — it offers to actually install what's missing (with a dry-run mode and a confirmation prompt before anything runs).

Requires Python 3.10+ and a working kubeconfig (the same one kubectl uses). For LLM-powered diagnosis, run Ollama locally (ollama pull llama3.1, the default — no API key needed), or point at a hosted provider instead: OpenAI, Anthropic (Claude), Google Gemini, or Groq — see Configuration below.

New to any of this? See PREREQUISITES.md for full install instructions (Python, kubectl, Ollama) and a hardware/model-size guide.

CLI usage

# List every failing pod in the cluster (or one namespace)
kube-assistant scan -n production

# Deep-dive: logs + events + LLM root-cause explanation + fix suggestions
kube-assistant diagnose api-7f8c9d -n production

# Same, but skip the LLM call and only use the rule-based fixes
kube-assistant diagnose api-7f8c9d -n production --no-llm

# Preview a fix (default: dry-run, no cluster mutation)
kube-assistant fix api-7f8c9d -n production --strategy restart

# Actually apply it (still asks for interactive confirmation unless -y)
kube-assistant fix api-7f8c9d -n production --strategy restart --no-dry-run

# Raise a Deployment's memory limit
kube-assistant fix api-7f8c9d -n production --strategy memory-patch \
    --deployment api --memory-limit 1Gi --no-dry-run

# Generate a plain manifest or a Helm chart
kube-assistant generate myapp --image myrepo/myapp:1.4.0 --kind manifest
kube-assistant generate myapp --image myrepo/myapp:1.4.0 --kind helm

Using it as an MCP server (Cursor / Claude Desktop)

Start it directly:

kube-assistant serve

Or point your MCP client config at it. Example for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kube-assistant": {
      "command": "kube-assistant",
      "args": ["serve"]
    }
  }
}

Exposed tools: list_failing_pods, get_pod_logs, diagnose_pod, apply_fix (dry-run by default, needs confirm=true), generate_manifest.

Configuration

kube-assistant supports five LLM backends. Set KUBE_ASSISTANT_LLM_BACKEND to pick one — everything else (model default, which API key to read) follows automatically:

# Example: use Claude instead of a local model
export KUBE_ASSISTANT_LLM_BACKEND=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
kube-assistant diagnose <pod> -n <namespace>

# Or per-command, without changing your shell's defaults:
kube-assistant diagnose <pod> --llm-backend gemini --llm-model gemini-2.0-flash

Other env vars:

Model names and aliases change over time — the defaults above are reasonable starting points, not guarantees; override with KUBE_ASSISTANT_LLM_MODEL if your provider has moved on. kube-assistant doctor checks that the right API key is set for whichever backend you've configured.

Adding a sixth provider is one small class in llm_client.py: subclass LLMBackend (or OpenAICompatibleBackend if it speaks the OpenAI chat shape) and register it in _BACKEND_CLASSES.

Architecture

CLI (Typer) ──┐
              ├──> K8sClient (kubernetes python client)
MCP (FastMCP)─┘         │
                         ▼
                  LogAnalyzer (regex patterns)
                         │
                         ▼
              RuleBasedFixer  +  LLMClient (Ollama / OpenAI)
                         │
                         ▼
                 AutoFixer (dry-run gated apply)
                         │
                         ▼
                ManifestGenerator (YAML / Helm)

Development

git clone https://github.com/yonatani94/kube-assistant-mcp
cd kube-assistant-mcp
make setup
pytest

The test suite mocks the Kubernetes API and the LLM backend, so pytest runs with no cluster and no network access.

Safety notes

This tool can delete Pods and patch Deployments. It is designed defensively:

• Every write path defaults to dry_run=True.
• A mutation only happens when the caller passes both dry_run=False and confirm=True (CLI: --no-dry-run + interactive confirm or --yes; MCP: confirm=true).
• It never deletes namespaces, PVCs, or Secrets.

Still, review the generated plan before confirming, especially in production namespaces.

License

MIT — see LICENSE.