K8s Gpu MCP Server

🚀 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

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

{
  "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个测试）。

📖 架构文档 →

可用工具

可用提示

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

使用Claude的示例用法：

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

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

操作模式

只读模式是默认模式，适用于大多数用例。操作员模式启用未来的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。

🤝 贡献

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

快速贡献指南

1. 查看 开放问题
2. 分叉并创建功能分支：git checkout -b feat/my-feature
3. 进行更改，添加测试
4. 运行检查：make all
5. 使用DCO提交：git commit -s -S -m "feat(scope): description"
6. 打开带有标签和里程碑的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讨论