K8s Gpu MCP Server

🚀 k8s-gpu-mcp-server

Kubernetes上のNVIDIA GPUクラスター用のリアルタイムSRE診断エージェントです。

🚀 クイックスタート

ワンクリックインストール

上のボタンをクリックすると、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

# ターゲットノード上のエージェントポッドを見つける
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に "What's the temperature of the GPUs?" と尋ねます。

📖 完全なクイックスタートガイド → | Kubernetesデプロイ →

✨ 主な機能

• 🎯 低リソース、常時利用可能 - 永続的なHTTPサーバー（アイドル時約15 - 20MB）は、ツールが呼び出されたときのみGPUの作業を実行します。
• 🔌 HTTPトランスポート - HTTP/SSE上のJSON-RPC 2.0（本番環境のデフォルト）
• 🔍 深いハードウェアアクセス - GPU診断のための直接的なNVML統合
• 🤖 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チャート（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

# またはグローバルにインストール
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

# モックGPUでテスト（ハードウェア不要）
cat examples/gpu_inventory.json | ./bin/agent --nvml-mode=mock

# 実際のGPUでテスト（NVIDIAドライバが必要）
cat examples/gpu_inventory.json | ./bin/agent --nvml-mode=real

📚 ドキュメント

• クイックスタートガイド - 5分で動かす方法
• Kubernetesデプロイ - K8sのデプロイと設定
• アーキテクチャ - システム設計とコンポーネント
• セキュリティモデル - RBACとセキュリティ設定
• MCPの使用方法 - MCPサーバーの利用方法
• 開発ガイド - コントリビューションガイドライン
• サンプル - サンプルJSON-RPCリクエスト

🔧 技術詳細

アーキテクチャ

┌─────────────────────────────────────────────────────────────────────┐
│                    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を介してエージェントポッドにルーティングします（約50msのレイテンシー）
• 低リソース - 永続的なHTTPサーバー、約15 - 20MBのメモリ
• 可観測性 - サーキットブレーカー、Prometheusメトリクス、分散トレーシング
• インターフェース抽象化 - テスト可能、柔軟性、ポータブル（538のテスト）

📖 アーキテクチャドキュメント →

利用可能なツール

利用可能なプロンプト

MCPプロンプトは、複数のツールを調整するガイド付き診断ワークフローを提供します。 プロンプトの定義については、 を参照してください。

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ツールを有効にします。

フライトレコーダー

エージェントには、GPUのテレメトリ（温度、電力、使用率、メモリ）を各GPUのリングバッファに継続的にキャプチャする組み込みのフライトレコーダー (pkg/blackbox) が含まれています。これにより、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有効)

🤝 コントリビューション

コントリビューションを歓迎します！詳細については、開発ガイド を参照してください。

簡単なコントリビューションガイド

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: "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?"

🏆 成果

• ✅ Go 1.25 - 最新のGoバージョン
• ✅ 実際のNVML - Tesla T4でテスト
• ✅ 550以上のテストが合格 - レースディテクターが有効、58 - 80%のカバレッジ
• ✅ HTTPファーストアーキテクチャ - execルーティングより150倍高速
• ✅ ゲートウェイ + サーキットブレーカー - 本番環境での信頼性
• ✅ MCPプロンプト - SREのトラブルシューティングのためのガイド付き診断ワークフロー
• ✅ Prometheusメトリクス - ノードごとのレイテンシー追跡
• ✅ 約8MBのバイナリ - 50MBの目標を84%下回っています
• ✅ MCP 2025-06-18 - 最新のプロトコルバージョン

📄 ライセンス

Apache License 2.0 - 詳細については LICENSE を参照してください。

🙏 謝辞

• NVIDIA NVML - GPU管理ライブラリ
• Model Context Protocol - MCP仕様
• mcp-go - MCPのGo実装
• Anthropic Claude - AIアシスタント
• Cursor - AIパワードIDE

📞 連絡先

メンテナー: @ArangoGutierrez
イシュー: GitHubイシュー
ディスカッション: GitHubディスカッション