金大哥 - k8s-gpu-mcp-server MCP 详情

article

README

🚀 k8s-gpu-mcp-server

k8s-gpu-mcp-server 是一个即时的SRE诊断代理，用于Kubernetes上的NVIDIA GPU集群。它借助模型上下文协议 (MCP)，为Kubernetes集群提供精准、实时的NVIDIA GPU硬件检查功能。与传统监控系统不同，该代理专为SRE进行AI辅助故障排除而设计，可用于调试标准Kubernetes API无法检测到的复杂硬件故障。

🚀 快速开始

一键安装

点击上面的按钮，可在Cursor中自动安装。

单行命令安装

# 使用npx（推荐）
npx k8s-gpu-mcp-server@latest

# 或者全局安装
npm install -g k8s-gpu-mcp-server

📋 手动配置：Cursor / VS Code

添加到 ~/.cursor/mcp.json（Cursor）或VS Code的MCP配置中：

{
  "mcpServers": {
    "k8s-gpu-mcp": {
      "command": "npx",
      "args": ["-y", "k8s-gpu-mcp-server@latest"]
    }
  }
}

📋 手动配置：Claude Desktop

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "k8s-gpu-mcp": {
      "command": "npx",
      "args": ["-y", "k8s-gpu-mcp-server@latest"]
    }
  }
}

从源代码安装

# 克隆并构建
git clone https://github.com/ArangoGutierrez/k8s-gpu-mcp-server.git
cd k8s-gpu-mcp-server
make agent

# 使用模拟GPU进行测试（无需硬件）
cat examples/gpu_inventory.json | ./bin/agent --nvml-mode=mock

# 使用真实GPU进行测试（需要NVIDIA驱动）
cat examples/gpu_inventory.json | ./bin/agent --nvml-mode=real

部署到Kubernetes

# 使用Helm OCI进行部署（推荐）
helm install k8s-gpu-mcp-server \
  oci://ghcr.io/arangogutierrez/charts/k8s-gpu-mcp-server \
  --namespace gpu-diagnostics --create-namespace

# 或者从本地图表部署
helm install k8s-gpu-mcp-server ./deployment/helm/k8s-gpu-mcp-server \
  --namespace gpu-diagnostics --create-namespace

# 在目标节点上查找代理Pod
NODE_NAME=<node-name>
POD=$(kubectl get pods -n gpu-diagnostics \
  -l app.kubernetes.io/name=k8s-gpu-mcp-server \
  --field-selector spec.nodeName=$NODE_NAME \
  -o jsonpath='{.items[0].metadata.name}')

# 启动诊断会话
kubectl exec -it -n gpu-diagnostics $POD -- /agent --mode=read-only

⚠️ 重要提示

GPU访问需要通过GPU Operator或nvidia-ctk配置 runtimeClassName: nvidia。对于没有RuntimeClass的集群，可使用回退配置：--set gpu.runtimeClass.enabled=false --set gpu.resourceRequest.enabled=true

使用kubectl配置Claude Desktop（高级）

对于已部署的代理，将以下内容添加到Claude Desktop配置中：

{
  "mcpServers": {
    "k8s-gpu-agent": {
      "command": "kubectl",
      "args": ["exec", "-i", "deploy/k8s-gpu-mcp-server", "-n", "gpu-diagnostics", "--", "/agent"]
    }
  }
}

然后向Claude提问：“GPU的温度是多少？”

📖 完整快速开始指南 → | Kubernetes部署 →

✨ 主要特性

🎯 低占用、随时可用：持久的HTTP服务器（空闲时约15 - 20MB）仅在调用工具时执行GPU工作。
🔌 HTTP传输：通过HTTP/SSE使用JSON-RPC 2.0（生产默认）。
🔍 深度硬件访问：直接集成NVML进行GPU诊断。
🤖 原生支持AI：为Claude Desktop、Cursor和MCP兼容主机构建。
📋 MCP提示：预构建的GPU诊断工作流，用于指导故障排除。
🔒 默认安全：只读操作，具有显式的操作员模式。
⚡ 生产就绪：在真实的Tesla T4上进行测试，通过550多个测试。

📦 安装指南

使用npm（推荐）

# 直接使用npx运行
npx k8s-gpu-mcp-server@latest

# 或者全局安装
npm install -g k8s-gpu-mcp-server

从源代码安装

git clone https://github.com/ArangoGutierrez/k8s-gpu-mcp-server.git
cd k8s-gpu-mcp-server
make agent
sudo mv bin/agent /usr/local/bin/k8s-gpu-mcp-server

使用Go安装

go install github.com/ArangoGutierrez/k8s-gpu-mcp-server/cmd/agent@latest

容器镜像安装

docker pull ghcr.io/arangogutierrez/k8s-gpu-mcp-server:latest

Helm Chart（OCI）安装

# 从GHCR OCI注册表安装
helm install k8s-gpu-mcp-server \
  oci://ghcr.io/arangogutierrez/charts/k8s-gpu-mcp-server \
  --namespace gpu-diagnostics --create-namespace

💻 使用示例

基础用法

# 使用npx运行
npx k8s-gpu-mcp-server@latest

高级用法

# 从源代码克隆并构建
git clone https://github.com/ArangoGutierrez/k8s-gpu-mcp-server.git
cd k8s-gpu-mcp-server
make agent
# 使用模拟GPU进行测试
cat examples/gpu_inventory.json | ./bin/agent --nvml-mode=mock

📚 详细文档

快速开始指南 - 5分钟内启动并运行。
Kubernetes部署 - K8s部署和配置。
架构 - 系统设计和组件。
安全模型 - RBAC和安全配置。
MCP使用 - 如何使用MCP服务器。
开发指南 - 贡献指南。
示例 - 示例JSON-RPC请求。

🔧 技术细节

架构

┌─────────────────────────────────────────────────────────────────────┐
│                    MCP客户端 (Claude/Cursor)                        │
└────────────────────────────┬────────────────────────────────────────┘
                             │ stdio / HTTP
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    网关Pod (:8080)                               │
│       路由器 → 断路器 → HTTP客户端                         │
└────────────────────────────┬────────────────────────────────────────┘
                             │ HTTP (Pod到Pod)
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  代理 (节点1) │  │  代理 (节点2) │  │  代理 (节点N) │
│  9个MCP工具    │  │  9个MCP工具    │  │  9个MCP工具    │
│  NVML → GPU     │  │  NVML → GPU     │  │  NVML → GPU     │
└─────────────────┘  └─────────────────┘  └─────────────────┘

设计原则：

以HTTP为先：网关通过HTTP将请求路由到代理Pod（约50ms延迟）。
低占用：持久的HTTP服务器，约15 - 20MB内存。
可观测性：断路器、Prometheus指标、分布式跟踪。
接口抽象：可测试、灵活、可移植（538个测试）。

📖 架构文档 →

可用工具

| 工具 | 描述 | 类别 | 状态 | |------|-------------|----------|--------| | get_gpu_inventory | 硬件清单 + 遥测数据 | NVML | ✅ 可用 | | get_gpu_health | 带评分的GPU健康监控 | NVML | ✅ 可用 | | analyze_xid_errors | 从内核日志解析GPU XID错误代码 | NVML | ✅ 可用 | | get_nvlink_topology | NVLink互连拓扑和健康状况 | NVML | ✅ 可用 | | get_gpu_timeline | 从飞行记录仪获取历史GPU指标 | NVML + 黑盒 | ✅ 可用 | | describe_gpu_node | 结合K8s元数据的节点级GPU诊断 | K8s + NVML | ✅ 可用 | | get_pod_gpu_allocation | 通过资源请求关联GPU和Pod | K8s | ✅ 可用 | | explain_failure | 对失败的GPU工作负载进行根本原因分析 | K8s + 事件 | ✅ 可用 | | get_incident_report | 带有时间线和快照的详细事件报告 | K8s + 事件 | ✅ 可用 | | kill_gpu_process | 终止GPU进程 | 操作员 | 🚧 M4（操作员） | | reset_gpu | GPU重置 | 操作员 | 🚧 M4（操作员） |

可用提示

MCP提示提供了指导诊断工作流，可编排多个工具。提示定义见 pkg/prompts/prompts.go。

| 提示 | 描述 | |--------|-------------| | gpu-health-check | 全面的GPU健康评估及建议 | | diagnose-xid-errors | 分析NVIDIA XID错误并提供修复指导 | | gpu-triage | 标准SRE分类工作流：清单 → 健康 → XID分析 |

使用Claude的示例用法：

你："对节点gpu-worker-5运行GPU分类工作流"

Claude：[执行gpu-triage提示]
        → 调用get_gpu_inventory、get_gpu_health、analyze_xid_errors
        → 返回带有建议的结构化分类报告

操作模式

| 模式 | 标志 | 描述 | |------|------|-------------| | 只读（默认） | --mode=read-only | 所有诊断工具，无修改操作 | | 操作员 | --mode=operator | 启用未来的修改操作（终止进程、重置GPU） |

只读模式是默认模式，适用于大多数用例。操作员模式启用未来的M4工具，可对GPU执行写操作。

飞行记录仪

代理包含一个内置的飞行记录仪 (pkg/blackbox)，可将GPU遥测数据（温度、功率、利用率、内存）持续捕获到每个GPU的环形缓冲区中。这使得 get_gpu_timeline 和 get_incident_report 等工具能够查询故障发生时的历史GPU指标。

飞行记录仪随代理自动启动，无需额外配置。数据在内存中保留配置的时间窗口（默认：30分钟）。

📖 MCP使用指南 →

📈 项目状态

当前里程碑：M3: Kubernetes集成

进度：约90%完成（HTTP传输 ✅，网关 ✅，K8s工具 ✅）

已完成里程碑

✅ M1: 基础与API - 2026年1月3日完成
✅ M2: 硬件检查 - 2026年1月10日完成
- 真实NVML集成，在Tesla T4上测试
- GPU健康监控，XID错误分析
- npm/Helm分发

近期更新（2026年1月）

1月17日：支持MCP提示 - 3个内置GPU诊断工作流
1月16日：为外部贡献者进行文档360度审查
1月15日：K8s工具完成 (describe_gpu_node, get_pod_gpu_allocation)
1月14日：HTTP传输史诗完成 - 延迟改善150倍
1月14日：跨节点网络修复（Calico VXLAN）
1月13日：支持断路器和Prometheus指标的网关模式

📊 查看所有里程碑 →

🧪 测试

单元测试（无需GPU）

make test                   # 运行所有单元测试（538个测试通过）
make coverage               # 生成覆盖率报告
make coverage-html          # 在浏览器中查看覆盖率

集成测试（需要GPU）

make test-integration       # 在GPU硬件上运行
# 或者手动运行
go test -tags=integration -v ./pkg/nvml/

最新测试结果：

✓ 共538个测试通过
✓ 启用竞态检测器 (-race)
✓ 覆盖率：按包计算为58 - 80%

在Tesla T4上进行集成测试：
  - GPU：Tesla T4（15GB）
  - 温度：29°C
  - 功率：13.9W
  - 所有NVML操作已验证

🏗️ 构建

# 为本地平台构建
make agent

# 为Linux构建（使用真实NVML）
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 make agent

# 构建容器镜像
make image

# 多架构发布构建
make dist

二进制文件大小：

模拟模式：4.3MB（禁用CGO）
真实模式：7.9MB（启用CGO）

📄 许可证

本项目采用Apache License 2.0许可协议，详情请参阅 LICENSE。

🤝 贡献

我们欢迎贡献！请参阅我们的开发指南了解详细信息。

快速贡献指南

查看开放问题
分叉并创建功能分支：git checkout -b feat/my-feature
进行更改，添加测试
运行检查：make all
使用DCO提交：git commit -s -S -m "feat(scope): description"
打开带有标签和里程碑的PR

📖 完整开发指南 →

🎯 使用案例

1. 调试卡住的训练作业

SRE：“节点-5上的训练作业为什么卡住了？”
Claude → k8s-gpu-mcp-server → 检测到XID 48（ECC错误）
Claude：“节点-5存在不可纠正的内存错误。立即排水。”

2. 热管理

SRE：“是否有GPU正在进行热节流？”
Claude → k8s-gpu-mcp-server → 检查温度和节流状态
Claude：“GPU 3温度为86°C，正在进行热节流。检查散热情况。”

3. 拓扑验证

SRE：“NVLink是否为多GPU训练正确配置？”
Claude → k8s-gpu-mcp-server → 检查NVLink拓扑
Claude：“所有8个GPU通过NVLink连接，带宽为600GB/s。”

4. 僵尸进程查找

SRE：“GPU内存已满，但没有运行的Pod”
Claude → k8s-gpu-mcp-server → 列出GPU进程
Claude：“发现僵尸进程PID 12345占用8GB内存。是否终止它？”

🏆 成就

✅ Go 1.25 - 最新的Go版本
✅ 真实NVML - 在Tesla T4上测试
✅ 550多个测试通过 - 启用竞态检测器，覆盖率58 - 80%
✅ 以HTTP为先的架构 - 比执行路由快150倍
✅ 网关 + 断路器 - 生产级可靠性
✅ MCP提示 - 用于SRE故障排除的指导诊断工作流
✅ Prometheus指标 - 按节点跟踪延迟
✅ 约8MB二进制文件 - 比50MB目标低84%
✅ MCP 2025-06-18 - 最新协议版本

🙏 致谢

NVIDIA NVML - GPU管理库
模型上下文协议 - MCP规范
mcp-go - MCP Go实现
Anthropic Claude - AI助手
Cursor - 人工智能驱动的IDE

📞 联系

维护者：@ArangoGutierrez
问题反馈：GitHub问题
讨论区：GitHub讨论

⭐ 在GitHub上给我们加星 — 这很有帮助！

报告Bug · 请求功能 · 查看路线图

k8s-gpu-mcp-server

README

🚀 k8s-gpu-mcp-server

🚀 快速开始

一键安装

单行命令安装

从源代码安装

部署到Kubernetes

使用kubectl配置Claude Desktop（高级）

✨ 主要特性

📦 安装指南

使用npm（推荐）

从源代码安装

使用Go安装

容器镜像安装

Helm Chart（OCI）安装

💻 使用示例

基础用法

高级用法

📚 详细文档

🔧 技术细节

架构

可用工具

可用提示

操作模式

飞行记录仪

📈 项目状态

当前里程碑：M3: Kubernetes集成

已完成里程碑

近期更新（2026年1月）

🧪 测试

单元测试（无需GPU）

集成测试（需要GPU）

🏗️ 构建

📄 许可证

🤝 贡献

快速贡献指南

🎯 使用案例

1. 调试卡住的训练作业

2. 热管理

3. 拓扑验证

4. 僵尸进程查找

🏆 成就

🙏 致谢

📞 联系

运行方式说明

托管运行

本地运行 / 其它方式