K8s Doctor

K8s Doctor MCP is an AI-powered Kubernetes diagnostics tool you run through an MCP server. It analyzes pod health, logs, events, and resource usage to identify root causes and provide concrete commands to fix issues, helping you move from symptom spotting to actionable remediation across your cluster.

How to use

Use an MCP client to interact with the K8s Doctor MCP server. You will access a set of tools that diagnose pod health, analyze logs, check resources, and perform cluster-wide health checks. Run commands through the MCP client to request diagnoses, view recommended fixes, and apply exact kubectl or YAML changes suggested by the AI.

How to install

Prerequisites: you need kubectl configured and working, a kubeconfig in the default location or KUBECONFIG set, Node.js 18 or higher, and access to your Kubernetes cluster.

Install the MCP server package globally via npm:

npm install -g @zerry_jin/k8s-doctor-mcp

How to install (from source)

If you prefer building from source, clone the repository, install dependencies, and build the project.

git clone https://github.com/ongjin/k8s-doctor-mcp.git
cd k8s-doctor-mcp
npm install
npm run build

Setup with Claude Code

After you have the MCP server installed, register it with Claude Code so you can access it from Claude.

# After npm global install
claude mcp add --scope project k8s-doctor -- k8s-doctor-mcp

# Or from source build
claude mcp add --scope project k8s-doctor -- node /path/to/k8s-doctor-mcp/dist/index.js

Quick Setup (Auto-approve Tools)

If you want tools to run without prompts, enable auto-approval for the most common tools.

For Claude Desktop App users, restart the app, ask your first question, and approve requests from this server when prompted.

For Claude Code users, adjust permissions to allow diagnostic tools globally or per-project.

# Recommended global permissions configuration
claude config add allowedTools \
  "mcp__k8s-doctor__diagnose-pod" \
  "mcp__k8s-doctor__debug-crashloop" \
  "mcp__k8s-doctor__analyze-logs" \
  "mcp__k8s-doctor__full-diagnosis"

Prerequisites and usage notes

Ensure you have a running Kubernetes cluster and your kubeconfig is accessible. You will use the MCP server to request AI-powered diagnostics and receive precise commands to fix issues.

Examples of use

For example, you can ask the MCP to diagnose a CrashLoopBackOff pod, analyze logs for a pod, or run a full cluster health check. The tool will return a health score, potential root causes, and exact commands or YAML snippets to apply.

Available tools

diagnose-pod

Comprehensive pod diagnostics that analyze status, events, resources, and provide a health score.

debug-crashloop

CrashLoopBackOff specialist that decodes exit codes, analyzes logs, and finds root cause.

analyze-logs

Smart log analysis that detects error patterns and suggests fixes.

check-resources

Resource usage checks that validate CPU/Memory limits and warn about OOM risks.

full-diagnosis

Cluster health check scanning all nodes and pods for issues.

check-events

Event analysis that filters and analyzes Warning events.

list-namespaces

Namespace listing for a quick overview of all namespaces.

list-pods

Pod listing with status indicators highlighting problematic pods.