triagekit-mcp-k8s-triage

Part of the TriageKit MCP server suite.

Diagnoses unhealthy Kubernetes workloads and finds resource right-sizing candidates using real cluster state — not another kubectl wrapper. Existing Kubernetes MCP servers mostly expose cluster CRUD; this one narrows hard on read-only diagnosis and right-sizing.

Why

When a pod is crash-looping, an on-call engineer pivots across kubectl describe, kubectl logs, rollout history, and (if they're lucky) a Grafana dashboard to figure out what's actually wrong. This server does that correlation directly: container exit codes and event reasons get mapped to a ranked failure category, crashes get checked against recent rollouts, and Prometheus usage history gets compared against resource requests — all as structured evidence, not another raw JSON dump.

Tools

Also exposes a resource (k8s://{context}/{namespace}/{workload}/diagnosis) and a prompt (incident_response_runbook) that walks an LLM through the standard triage sequence.

This server is read-only by design — see SECURITY.md. It never creates, updates, or deletes cluster resources.

Install

Not yet published. This package itself is not on PyPI yet (alpha, pre-release) - its dependency triagekit-mcp-core is. Once this package is published, install with uvx triagekit-mcp-k8s-triage or pip install triagekit-mcp-k8s-triage. Until then, build locally: uv build --out-dir dist && uv pip install dist/*.whl.

Quick Start (Claude Desktop / Claude Code)

Add to your mcp.json:

{
  "mcpServers": {
    "k8s-triage": {
      "command": "uvx",
      "args": ["triagekit-mcp-k8s-triage"],
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig"
      }
    }
  }
}

Example prompts

• "Why is the checkout deployment in prod crash-looping?"
• "Walk me through the incident response runbook for the payments-api pod in staging."
• "Show me the event timeline for pod worker-7f9c8d-abc12 in default."
• "Give me logs for api-server since its last restart, not the old crash logs."
• "Did the last rollout of checkout in prod cause these crashes?"
• "Is anything in prod over- or under-provisioned based on the last 7 days of usage?"
• "Give me a cluster health summary for prod."

Authentication

Recommended minimum-privilege RBAC — a read-only ClusterRole covering exactly what these tools use:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: triagekit-k8s-triage-readonly
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log", "events", "nodes"]
    verbs: ["get", "list"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets"]
    verbs: ["get", "list"]
  - apiGroups: ["policy"]
    resources: ["poddisruptionbudgets"]
    verbs: ["get", "list"]
  - apiGroups: ["autoscaling"]
    resources: ["horizontalpodautoscalers"]
    verbs: ["get", "list"]

Credentials are only ever read from the environment/kubeconfig at startup — no tool accepts a credential as a parameter. See CONTRIBUTING.md for why.

Development

uv sync
uv run pytest -v
uv run ruff check .
uv run pyright

Tests never talk to a real cluster — KubeClient and PrometheusClient are constructed from mocked API objects/HTTP responses in every test.

License

MIT