K8s Gpu MCP Server

k8s gpu mcp服务器

Kubernetes上NVIDIA GPU集群的实时SRE诊断代理

](https://go.dev/)   ](https://github.com/ArangoGutierrez/k8s-gpu-mcp-server/issues) ](https://github.com/ArangoGutierrez/k8s-gpu-mcp-server) 

______________________________________________________________________

概述

k8s-gpu-mcp-server 是一个 短暂诊断剂 其提供外科手术， 通过以下方式对Kubernetes集群进行实时NVIDIA GPU硬件自检 模型上下文协议（MCP）.

与传统的监控系统不同，此代理旨在 人工智能辅助 故障排除 通过SRE调试标准的复杂硬件故障 Kubernetes API无法检测。

✨ 主要特点

• 🎯 占地面积小，始终可用 -持久HTTP服务器（~15-20MB空闲）仅在调用工具时执行GPU工作
• 🔌 HTTP传输 -HTTP/SSE上的JSON-RPC 2.0（生产默认）
• 🔍 深度硬件访问 -GPU诊断的直接NVML集成
• 🤖 人工智能原生 -专为Claude Desktop、Cursor和MCP兼容主机构建
• 📋 MCP提示 -预构建的GPU诊断工作流程，用于指导故障排除
• 🔒 缺省巩固安全 -具有显式运算符模式的只读操作
• ⚡ 生产就绪 -真正的特斯拉T4测试，550多项测试通过

______________________________________________________________________

🚀 快速开始

一键安装


单击上面的按钮在Cursor中自动安装。

单线安装

# Using npx (recommended)
npx k8s-gpu-mcp-server@latest

# Or install globally
npm install -g k8s-gpu-mcp-server

📋 Manual Configuration: Cursor / VS Code

增添 ~/.cursor/mcp.json （光标）或VS代码MCP配置：

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

📋 Manual Configuration: Claude Desktop

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

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

从源代码安装

# Clone and build
git clone https://github.com/ArangoGutierrez/k8s-gpu-mcp-server.git
cd k8s-gpu-mcp-server
make agent

# Test with mock GPUs (no hardware required)
cat examples/gpu_inventory.json | ./bin/agent --nvml-mode=mock

# Test with real GPU (requires NVIDIA driver)
cat examples/gpu_inventory.json | ./bin/agent --nvml-mode=real

部署到Kubernetes

# Deploy with Helm OCI (recommended)
helm install k8s-gpu-mcp-server \
  oci://ghcr.io/arangogutierrez/charts/k8s-gpu-mcp-server \
  --namespace gpu-diagnostics --create-namespace

# Or from local chart
helm install k8s-gpu-mcp-server ./deployment/helm/k8s-gpu-mcp-server \
  --namespace gpu-diagnostics --create-namespace

# Find agent pod on target node
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}')

# Start diagnostic session
kubectl exec -it -n gpu-diagnostics $POD -- /agent --mode=read-only

注： GPU访问需要 runtimeClassName: nvidia 配置如下 GPU操作员或nvidia ctk。对于没有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"]
    }
  }
}

然后问克劳德： *“GPU的温度是多少？”*

📖 完整快速入门指南→ | Kubernetes部署→

______________________________________________________________________

📊 建筑

┌─────────────────────────────────────────────────────────────────────┐
│                    MCP Client (Claude/Cursor)                        │
└────────────────────────────┬────────────────────────────────────────┘
                             │ stdio / HTTP
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Gateway Pod (:8080)                               │
│       Router → Circuit Breaker → HTTP Client                         │
└────────────────────────────┬────────────────────────────────────────┘
                             │ HTTP (pod-to-pod)
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Agent (Node 1) │  │  Agent (Node 2) │  │  Agent (Node N) │
│  9 MCP Tools    │  │  9 MCP Tools    │  │  9 MCP Tools    │
│  NVML → GPU     │  │  NVML → GPU     │  │  NVML → GPU     │
└─────────────────┘  └─────────────────┘  └─────────────────┘

设计原则：

• HTTP优先：网关通过HTTP路由到代理Pod（延迟约50ms）
• 低占地面积：持久HTTP服务器，~15-20MB内存
• 可观察对象：断路器、普罗米修斯指标、分布式跟踪
• 接口抽象：可测试、灵活、便携（538次测试）

📖 架构文档→

______________________________________________________________________

🛠️ 可用工具

📋 可用提示

MCP Prompts提供编排多个工具的指导性诊断工作流程。 看 pkg/prompts/prompts.go 以获得快速定义。

Claude的用法示例：

You: "Run the GPU triage workflow for node gpu-worker-5"

Claude: [Executes gpu-triage prompt]
        → Calls get_gpu_inventory, get_gpu_health, analyze_xid_errors
        → Returns structured triage report with recommendations

🔒 操作模式

只读模式是默认模式，建议用于大多数用例。操作员模式 支持在GPU上执行写入操作的未来M4工具。

📼 飞行记录器

该代理包括一个内置的飞行记录器(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集成，在特斯拉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传输Epic完成-延迟改善150倍
• 1月14日：跨节点网络修复（Calico VXLAN）
• 1月13日：带断路器和普罗米修斯指标的网关模式

📊 查看所有里程碑→

______________________________________________________________________

🧪 测试

单元测试（无需GPU）

make test                   # Run all unit tests (538 tests passing)
make coverage               # Generate coverage report
make coverage-html          # View coverage in browser

集成测试（需要GPU）

make test-integration       # Run on GPU hardware
# Or manually:
go test -tags=integration -v ./pkg/nvml/

最新测试结果：

✓ 538 total tests passing
✓ Race detector enabled (-race)
✓ Coverage: 58-80% by package

Integration tested on Tesla T4:
  - GPU: Tesla T4 (15GB)
  - Temperature: 29°C
  - Power: 13.9W
  - All NVML operations verified

______________________________________________________________________

🏗️ 构建

# Build for local platform
make agent

# Build for Linux (with real NVML)
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 make agent

# Build container image
make image

# Multi-arch release builds
make dist

二进制大小：

• 模拟模式： 430万桶 （CGO禁用）
• 真实模式： 7.9毫巴 （CGO已启用）

______________________________________________________________________

📦 安装

使用npm（推荐）

# Run directly with npx
npx k8s-gpu-mcp-server@latest

# Or install globally
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图表（OCI）

# Install from GHCR OCI registry
helm install k8s-gpu-mcp-server \
  oci://ghcr.io/arangogutierrez/charts/k8s-gpu-mcp-server \
  --namespace gpu-diagnostics --create-namespace

______________________________________________________________________

🤝 贡献

我们欢迎捐款！请查看我们的 开发指南 了解详情。

快速贡献指南

1. 检查 问题
2. 分叉并创建特征分支： git checkout -b feat/my-feature
3. 进行更改，添加测试
4. 运行检查： make all
5. 向DCO承诺： git commit -s -S -m "feat(scope): description"
6. 带有标签和里程碑的公开公关

📖 完整开发指南→

______________________________________________________________________

📚 文档

• 快速入门指南 -5分钟后开始跑步
• Kubernetes部署 -K8s部署和配置
• 建筑 -系统设计和组件
• 安全模型 -RBAC和安全配置
• MCP使用 -如何使用MCP服务器
• 开发指南 -贡献指南
• 例子 -JSON-RPC请求示例

______________________________________________________________________

🔧 技术栈

• 语言：转到1.25+（最新稳定）
• MCP协议: mcp版本0.43.2
• GPU库: 去nvml v0.13.0-1
• 测试: 证明v1.10.0
• 容器：Debian 12发行版（M3版本）

______________________________________________________________________

🎯 用例

1.调试卡住的培训工作

SRE: "Why is the training job on node-5 stuck?"
Claude → k8s-gpu-mcp-server → Detects XID 48 (ECC Error)
Claude: "Node-5 has uncorrectable memory errors. Drain immediately."

2.热管理

SRE: "Are any GPUs thermal throttling?"
Claude → k8s-gpu-mcp-server → Checks temps and throttle status
Claude: "GPU 3 is at 86°C and thermal throttling. Check cooling."

3.拓扑验证

SRE: "Is NVLink properly configured for multi-GPU training?"
Claude → k8s-gpu-mcp-server → Inspects NVLink topology
Claude: "All 8 GPUs connected via NVLink, 600GB/s bandwidth."

4.僵尸进程狩猎

SRE: "GPU memory is full but no pods are running"
Claude → k8s-gpu-mcp-server → Lists GPU processes
Claude: "Found zombie process PID 12345 using 8GB. Kill it?"

______________________________________________________________________

🏆 成就

• ✅ 转到1.25 -最新Go版本
• ✅ 真实NVML -在特斯拉T4上测试
• ✅ 550+测试通过 -种族检测器已启用，覆盖率为58-80%
• ✅ HTTP优先架构 -比exec路由快150倍
• ✅ 网关+断路器 -生产级可靠性
• ✅ MCP提示 -SRE故障排除的指导性诊断工作流程
• ✅ 普罗米修斯指标 -每节点延迟跟踪
• ✅ ~8MB二进制文件 -84%低于50MB目标
• ✅ MCP 2025-06-18 -最新协议版本

______________________________________________________________________

📄 许可证

Apache许可证2.0-请参阅 许可证 了解详情。

______________________________________________________________________

🙏 致谢

• 英伟达NVML -GPU管理库
• 模型上下文协议 -MCP规范
• mcp走 -MCP Go实施
• 安thropic克劳德 -AI助手
• 光标 -AI驱动的IDE

______________________________________________________________________

📞 联系

维护人员： @阿兰戈古铁雷斯\ 问题： \ 讨论：

______________________________________________________________________

⭐ 把我们放在GitHub上——这很有帮助！

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