K8s Doctor MCP

🏥 K8s医生MCP

基于人工智能的Kubernetes集群诊断和智能调试建议

](https://www.npmjs.com/package/@zerry_jin/k8s-doctor-mcp) ](https://www.npmjs.com/package/@zerry_jin/k8s-doctor-mcp)  ](https://nodejs.org) 

英语 | 韩语

演示

K8s Doctor Demo

为什么选择K8s医生？

当Kubernetes问题出现时，开发人员通常会经历一个无休止的循环：

• kubectl get pods
• kubectl logs
• kubectl describe
• 疯狂搜索StackOverflow。..

K8s医生改变了游戏。 它不仅仅是一个kubectl包装器，它是一个AI驱动的诊断工具，可以：

• 🔍 分析根本原因 -超越简单的状态检查
• 🧠 检测错误模式 -识别常见问题（连接被拒绝、OOM、DNS故障）
• 💡 提供可操作的解决方案 -为您提供精确的kubectl命令来解决问题
• 📊 退出代码分析 -解释出口1371431的实际含义
• 🎯 日志模式匹配 -在数千条记录行中查找信号
• 🏥 健康评分 -对你的吊舱/集群健康状况进行0-100的评分

特性

安装

通过npm（推荐）

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

来源

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

使用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

快速设置（自动批准工具）

厌倦了每次手动批准工具执行？按照以下步骤启用自动审批。

🖥️ 适用于Claude桌面应用程序用户

1. 重新启动Claude桌面应用程序。
2. 用以下方式问你的第一个问题 k8s-doctor.
3. 当权限对话框出现时，选中该框 “始终允许来自此服务器的请求” 然后单击 允许.

（未来的请求将自动执行，无需提示。）

⌨️ 适用于Claude Code（CLI）用户

如果您正在使用 claude 终端命令，通过交互式菜单管理权限：

1. 跑 claude 在你的终端。
2. 类型 /permissions 在提示中，按Enter键。
3. 选择 全局权限 （或项目权限）> 允许使用的工具.
4. 进入 mcp__k8s-doctor__* 允许所有工具，或单独添加特定工具。

💡 小贴士：对于大多数用例，允许 diagnose-pod, debug-crashloop，以及 analyze-logs 足够了。这三个场景涵盖了90%的调试场景。

推荐配置：

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

先决条件

• kubectl 的 已配置并工作(kubectl cluster-info 应该成功）
• kubeconfig 文件位于默认位置(~/.kube/config)或 KUBECONFIG 有人看过
• Node.js 18岁或以上
• 访问Kubernetes集群（本地，如minikube/cind，或远程）

使用示例

示例1：诊断碰撞循环吊舱

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:

resources: limits: memory: "512Mi" # Increase from current value

相关日志：

- 第1234行：错误：JavaScript堆内存不足
- 第1256行：严重错误：已达到堆限制

Example 2: Analyze Application Logs

你：“分析pod‘后端worker’的日志，告诉我什么是失败的”

Claude（使用分析日志）：
📝 日志分析

检测到的错误模式：

🔴 数据库连接错误（15次）
可能的原因：

- 数据库服务未就绪
- 连接字符串错误
- 认证失败

解决：

- 检查DB吊舱状态
- 验证环境变量（ConfigMap/Resecret）
- 检查服务端点：kubectl获取端点

🟡 超时（8次）
可能原因：响应时间太慢或网络延迟
解决方案：增加超时值或优化服务性能

Example 3: Cluster Health Check

您：“检查整体群集运行状况”

克劳德（使用完整诊断）：
🏥 集群健康诊断

总分：72/100💛

节点：3/3就绪✅
Pod：45/52跑步

- 碰撞循环：2🔥
- 待定：5⏳

关键问题：
🔴 Pod“支付服务”崩溃循环（出口1）
🔴 Pod“worker-3”OOM被杀

建议：

- 立即修复2个CrashLoop吊舱
- 检查挂起的Pod是否缺少资源

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医生mcp/
├── src/
│   ├── index.ts#MCP服务器及其所有工具
│   ├── types.ts#TypeScript类型定义
│   ├── 诊断学/
│   │   ├── pod-dignostics.ts#pod健康分析
│   │   └── cluster-health.ts#集群范围的诊断
│   ├── 分析器/
│   │   └── log-analyzer.ts#智能日志模式匹配
│   └── utils/
│       ├── k8s-client.ts#Kubernetes API客户端
│       └── formatters.ts#输出格式化工具
└── 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"

# Verify kubectl works
kubectl cluster-info

# Check kubeconfig location
echo $KUBECONFIG

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

“权限被拒绝”

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

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

“连接拒绝群集”

# Verify cluster connectivity
kubectl get nodes

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

发展

# 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

贡献

欢迎投稿！特别是：

• 🆕 新的错误模式检测
• 🌍 国际化（更多语言）
• 📊 度量集成（普罗米修斯等）
• 🧪 测试覆盖率
• 📖 文档改进

路线图

• \[\]度量服务器集成（实时CPU/内存使用率）
• \[\]网络策略诊断
• \[\]存储/PVC故障排除
• \[\]Helm图表分析
• \[\]多集群支持
• \[\]交互式调试模式
• \[\]导出报告（PDF、HTML）

许可证

MIT© 泽里

致谢

内置：

• @模型上下文协议/sdk -模型上下文协议
• @kubernetes/客户端节点 -Kubernetes JavaScript客户端
• 克劳德代码 -人工智能驱动的开发

星迹

如果此工具为您节省了调试时间，请⭐ 明星回购！

作者

泽里

• github： @泽里
• 为厌倦kubectl地狱的DevOps社区创建😅

______________________________________________________________________

制作❤️ 对于淹没在日志中的Kubernetes用户