kubernetes-diagnostics-mcp-server

A Model Context Protocol (MCP) server, in Go, that gives an LLM five diagnostic tools over a 280,000-event synthetic Kubernetes cluster, plus a benchmark that scores four anomaly-detection methods against the cluster's injected ground-truth faults. It speaks JSON-RPC over stdio (initialize, tools/list, tools/call) and drops straight into Claude Desktop.

The challenge

Cluster alerting usually keys on pod restarts, and that is exactly wrong twice over. Image-pull failures barely restart, so a restart alarm never sees them; and flaky-but-healthy pods restart often, so a restart alarm fires on pods that are fine. The result is an alerting method that is simultaneously blind and trigger happy. This server's benchmark quantifies that, and shows what to alarm on instead.

Use case

Use it as a worked example of an MCP tool server with a real evaluation behind its tools: how to structure JSON-RPC tools, and why the detection logic behind detect_anomalies should correlate hard-failure events rather than count restarts.

MCP tools

Headline result

280,000 events · 4,800 pods · 80 namespaces · 727 faulty pods · 12% flaky-healthy.

Root-cause inference accuracy (dominant-event mapping): 1.000 on faulty pods.

• Restart-based alerting is the worst method by far (F1 0.30). It misses image-pull faults, which barely restart, and flags flaky-healthy pods, which restart a lot. Both failure modes at once.
• A global problem-rate threshold (error_rate) recovers recall (0.92) but pays for it in precision (0.69) because flaky-healthy pods clear the bar.
• Correlating hard-failure events (OOM, crash, image-pull, node) is near perfect (F1 0.99) because those events are something a flaky-but-healthy pod never emits, so precision stays at 1.00 while recall stays high.
• The lesson for the tool: alarm on the kind of event, not the rate of restarts.

Run it as an MCP server

go build -o bin/k8sdiag ./cmd/k8sdiag
./bin/k8sdiag serve     # JSON-RPC over stdio

Hook it into Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kubernetes-diagnostics": {
      "command": "/abs/path/to/bin/k8sdiag",
      "args": ["serve"]
    }
  }
}

A quick manual smoke test:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./bin/k8sdiag serve

Chart gallery

Test pyramid

            /\        detection + root-cause benchmark (bench_test)
           /  \
          /----\      MCP protocol: init/list/call/errors/serve (protocol_test)
         /      \
        /--------\    cluster generation + fault signatures (cluster_test)
       /__________\   12 tests total

Quickstart

make test        

... [View full README on GitHub](https://github.com/Keshetti-Nikhil/kubernetes-diagnostics-mcp-server#readme)