🏥 K8s Doctor MCP

AI-powered Kubernetes cluster diagnostics and intelligent debugging recommendations

English | 한국어

Demo

<!-- Add your demo GIF here -->

Why K8s Doctor?

When a Kubernetes issue strikes, developers typically run through an endless loop of:

• kubectl get pods
• kubectl logs
• kubectl describe
• Frantically searching StackOverflow...

K8s Doctor changes the game. It's not just a kubectl wrapper - it's an AI-powered diagnostic tool that:

• 🔍 Analyzes root causes - Goes beyond simple status checks
• 🧠 Detects error patterns - Recognizes common issues (Connection Refused, OOM, DNS failures)
• 💡 Provides actionable solutions - Gives you exact kubectl commands to fix problems
• 📊 Exit code analysis - Explains what exit 137, 143, 1 actually mean
• 🎯 Log pattern matching - Finds the signal in thousands of log lines
• 🏥 Health scoring - Rates your pod/cluster health 0-100

Features

Tool	Description
diagnose-pod	Comprehensive pod diagnostics - analyzes status, events, resources, and provides health score
debug-crashloop	CrashLoopBackOff specialist - decodes exit codes, analyzes logs, finds root cause
analyze-logs	Smart log analysis - detects error patterns, suggests fixes for common issues
check-resources	Resource usage - validates CPU/Memory limits, warns about OOM risks
full-diagnosis	Cluster health check - scans all nodes and pods for issues
check-events	Event analysis - filters and analyzes Warning events
list-namespaces	Namespace listing - quick overview of all namespaces
list-pods	Pod listing - shows problematic pods with status indicators

Installation

Via npm (recommended)

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

From source

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

Setup with Claude Code

# 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)

Tired of manually approving tool execution every time? Follow these steps to enable auto-approval.

🖥️ For Claude Desktop App Users

1. Restart the Claude Desktop App.
2. Ask your first question using k8s-doctor.
3. When the permission dialog appears, check the box "Always allow requests from this server" and click Allow. (Future requests will execute automatically without prompts.)

⌨️ For Claude Code (CLI) Users

If you are using the claude terminal command, manage permissions via the interactive menu:

1. Run claude in your terminal.
2. Type /permissions in the prompt and press Enter.
3. Select Global Permissions (or Project Permissions) > Allowed Tools.
4. Enter mcp__k8s-doctor__* to allow all tools, or add specific tools individually.

💡 Tip: For most use cases, allowing diagnose-pod, debug-crashloop, and analyze-logs is sufficient. These three cover 90% of debugging scenarios.

Recommended configuration:

# Balanced approach - allow main diagnostic tools
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

• kubectl configured and working (kubectl cluster-info should succeed)
• kubeconfig file in default location (~/.kube/config) or KUBECONFIG env var set
• Node.js 18 or higher
• Access to a Kubernetes cluster (local like minikube/kind, or remote)

Usage Examples

Example 1: Diagnose a CrashLooping Pod

You: "My pod 'api-server' in namespace 'production' is CrashLooping. What's wrong?"

Claude (using k8s-doctor):
🔍 CrashLoopBackOff 진단

Exit Code: 137 (OOM Killed)
Root Cause: Container was killed due to Out Of Memory

Solution:
Increase memory limit:
```yaml
resources:
  limits:
    memory: "512Mi"  # Increase from current value

Relevant logs:

• Line 1234: Error: JavaScript heap out of memory
• Line 1256: FATAL ERROR: Reached heap limit

### Example 2: Analyze Application Logs

You: "Analyze logs for pod 'backend-worker' and tell me what's failing"

Claude (using analyze-logs): 📝 Log Analysis

Detected Error Patterns:

🔴 Database Connection Error (15 occurrences) Possible Causes:

• DB service not ready
• Wrong connection string
• Authentication failed

Solutions:

• Check DB pod status
• Verify environment variables (ConfigMap/Secret)
• Check service endpoints: kubectl get endpoints

🟡 Timeout (8 occurrences) Likely cause: Response time too slow or network delay Solution: Increase timeout values or optimize service performance

### Example 3: Cluster Health Check

You: "Check overall cluster health"

Claude (using full-diagnosis): 🏥 Cluster Health Diagnosis

Overall Score: 72/100 💛

Nodes: 3/3 Ready ✅ Pods: 45/52 Running

• CrashLoop: 2 🔥
• Pending: 5 ⏳

Critical Issues: 🔴 Pod "payment-service" CrashLooping (exit 1) 🔴 Pod "worker-3" OOM Killed

Recommendations:

• Fix 2 CrashLoop pods immediately
• Check if pending pods lack resources

## How It Works

1. **Connects to your cluster** via kubeconfig (same as kubectl)
2. **Gathers comprehensive data** - pod status, events, logs, resource usage
3. **Applies pattern matching** - recognizes common error patterns from production experience
4. **Analyzes root causes** - doesn't just show status, explains WHY it's failing
5. **Provides solutions** - gives exact commands and YAML to fix issues

## Error Patterns Detected

K8s Doctor recognizes these common patterns:

- 🔴 **Connection Refused** - Service not ready, wrong port, network policy
- 🔴 **Database Connection Errors** - DB auth, wrong connection strings
- 🔴 **Out of Memory** - OOM kills, memory leaks, undersized limits
- 🟠 **File Not Found** - ConfigMap not mounted, wrong paths
- 🟠 **Permission Denied** - SecurityContext issues, fsGroup problems
- 🟠 **DNS Resolution Failed** - CoreDNS issues, wrong service names
- 🟡 **Port Already in Use** - Multiple processes on same port
- 🟡 **Timeout** - Slow responses, network delays
- 🟡 **SSL/TLS Errors** - Expired certs, missing CA bundles

## Architecture

k8s-doctor-mcp/ ├── src/ │ ├── index.ts # MCP server with all tools │ ├── types.ts # TypeScript type definitions │ ├── diagnostics/ │ │ ├── pod-diagnostics.ts # Pod health analysis │ │ └── cluster-health.ts # Cluster-wide diagnostics │ ├── analyzers/ │ │ └── log-analyzer.ts # Smart log pattern matching │ └── utils/ │ ├── k8s-client.ts # Kubernetes API client │ └── formatters.ts # Output formatting utilities └── package.json

## Security Considerations

- K8s Doctor uses **read-only** Kubernetes API calls (list, get, describe)
- Requires same permissions as `kubectl get/describe/logs`
- Never modifies cluster state
- kubeconfig credentials stay local
- No data sent to external servers

## Troubleshooting

### "kubeconfig not found"
```bash
# Verify kubectl works
kubectl cluster-info

# Check kubeconfig location
echo $KUBECONFIG

# Test with explicit path
export KUBECONFIG=~/.kube/config

"Permission denied"

# Check your cluster permissions
kubectl auth can-i get pods --all-namespaces

# You need at least read access to:
# - pods, events, namespaces, nodes

"Connection refused to cluster"

# Verify cluster connectivity
kubectl get nodes

# For local clusters (minikube/kind)
minikube status
kind get clusters

Development

# Clone and install
git clone https://github.com/ongjin/k8s-doctor-mcp.git
cd k8s-doctor-mcp
npm install

# Development mode
npm run dev

# Build
npm run build

# Test with Claude Code
npm run build
claude mcp add --scope project k8s-doctor-dev -- node $(pwd)/dist/index.js

Contributing

Contributions welcome! Especially:

• 🆕 New error pattern detections
• 🌍 Internationalization (more languages)
• 📊 Metrics integration (Prometheus, etc.)
• 🧪 Test coverage
• 📖 Documentation improvements

Roadmap

• [ ] Metrics Server integration (real-time CPU/Memory usage)
• [ ] Network policy diagnostics
• [ ] Storage/PVC troubleshooting
• [ ] Helm chart analysis
• [ ] Multi-cluster support
• [ ] Interactive debugging mode
• [ ] Export reports (PDF, HTML)

License

MIT © zerry

Acknowledgments

Built with:

• @modelcontextprotocol/sdk - Model Context Protocol
• @kubernetes/client-node - Kubernetes JavaScript Client
• Claude Code - AI-powered development

Star History

If this tool saves you debugging time, please ⭐ star the repo!

Author

zerry

• GitHub: @zerry
• Created for the DevOps community who are tired of kubectl hell 😅

---

Made with ❤️ for Kubernetes users drowning in logs