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討論