K8s MCP Server

K8s MCP Server

K8s MCP Server は、Anthropic の Model Context Protocol（MCP）を実装した Docker ベースのサーバーです。Claude がセキュアなコンテナ環境で Kubernetes CLI ツール（kubectl、istioctl、helm、argocd）を実行できるようにします。

デモ：WordPress のデプロイとトラブルシューティング

セッション 1： k8s-mcp-server と Helm CLI を使用して、claude-demo 名前空間に WordPress アプリケーションをデプロイし、MariaDB StatefulSet を意図的にゼロにスケールして問題を発生させます。

セッション 2： k8s-mcp-server と kubectl コマンドを使用して、問題が発生した WordPress サイトを診断し、データベースがない問題を特定して、StatefulSet をスケールアップし、Ingress アクセスを設定して修復するトラブルシューティングセッションです。

デモ

仕組み

flowchart LR
    A[User] --> |Asks K8s question| B[Claude]
    B --> |Sends command via MCP| C[K8s MCP Server]
    C --> |Executes kubectl, helm, etc.| D[Kubernetes Cluster]
    D --> |Returns results| C
    C --> |Returns formatted results| B
    B --> |Analyzes & explains| A

Claude は、次のような支援をユーザーに提供できます。

• 複雑な Kubernetes の概念を説明する
• クラスターに対してコマンドを実行する
• 問題をトラブルシューティングする
• 最適化を提案する
• Kubernetes マニフェストを作成する

Claude Desktop ですばやく始める

2 分以内に、Claude が Kubernetes クラスターを操作できるようにします。

1. Claude Desktop の設定ファイルを作成または更新します。

   • macOS：$HOME/Library/Application Support/Claude/claude_desktop_config.json を編集します
   • Windows：%APPDATA%\Claude\claude_desktop_config.json を編集します
   • Linux：$HOME/.config/Claude/claude_desktop_config.json を編集します

   {
     "mcpServers": {
       "kubernetes": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
           "ghcr.io/alexei-led/k8s-mcp-server:latest"
         ]
       }
     }
   }
   

2. Claude Desktop を再起動します

   • 再起動後、入力欄の右下にツールアイコン（🔨）が表示されます
   • これは、Claude が MCP サーバー経由で K8s ツールにアクセスできるようになったことを示します

3. Claude Desktop で K8s ツールを直接使い始めます。

   • 「利用可能な Kubernetes コンテキストを教えてください」
   • 「default 名前空間のすべての Pod を表示してください」
   • 「nginx:1.21 のレプリカ数を 3 にしてデプロイメントを作成してください」
   • 「名前空間 'prod' の StatefulSet 'database' の問題点を説明してください」
   • 「bitnami/wordpress チャートを Helm でデプロイし、サービスの種類を LoadBalancer に設定してください」

注：Claude Desktop は K8s コマンドを MCP サーバー経由で自動的に処理するため、Claude の画面を離れずにクラスターについて自然な会話ができます。

クラウドプロバイダー：AWS EKS、GKE、Azure AKS を使用するには、追加の設定が必要です。クラウドプロバイダーのサポートガイドを参照してください。

機能

• 複数の Kubernetes ツール：kubectl、helm、istioctl、argocd を 1 つのコンテナーで利用できます
• クラウドプロバイダー：AWS EKS、Google GKE、Azure AKS をネイティブにサポートします
• セキュリティ：非 root ユーザーとして実行し、厳格なコマンド検証を行います
• コマンドのパイプ処理：jq、grep、sed などの一般的な Unix ツールをサポートします
• 簡単な設定：カスタマイズにはシンプルな環境変数を使用できます

トランスポートプロトコル

サーバーは 3 つのトランスポートプロトコルをサポートしており、K8S_MCP_TRANSPORT で設定できます。

トランスポート	説明	デフォルト
stdio	標準入出力（Claude Desktop のデフォルト）	はい
streamable-http	HTTP トランスポート（リモート／Web クライアントに推奨、MCP 仕様 2025-11-25）	いいえ
sse	Server-Sent Events（非推奨。代わりに streamable-http を使用してください）	いいえ

Streamable HTTP トランスポートを使用する例：

docker run --rm -p 8000:8000 \
  -v ~/.kube:/home/appuser/.kube:ro \
  -e K8S_MCP_TRANSPORT=streamable-http \
  ghcr.io/alexei-led/k8s-mcp-server:latest

注：Docker で HTTP トランスポートを使用して実行する場合、ポートマッピングが正しく機能するよう、サーバーは自動的に 0.0.0.0 にバインドします。Docker の外部では 127.0.0.1 にバインドします。

ドキュメント

• はじめに - 詳細なセットアップ手順
• クラウドプロバイダーのサポート - EKS、GKE、AKS の設定
• サポート対象のツール - 含まれる CLI ツールの完全な一覧
• 環境変数 - 設定オプション
• セキュリティ機能 - セキュリティモードとカスタムルール
• Claude との統合 - Claude Desktop の詳細なセットアップ
• アーキテクチャ - システムのアーキテクチャとコンポーネント
• 詳細仕様 - 技術仕様の詳細

使用例

接続後は、自然言語で Kubernetes のタスクを Claude に依頼できます。

flowchart TB
    subgraph "Basic Commands"
        A1["Show me all pods in the default namespace"]
        A2["Get all services across all namespaces"]
        A3["Display the logs for the nginx pod"]
    end
    
    subgraph "Troubleshooting"
        B1["Why is my deployment not starting?"]
        B2["Describe the failing pod and explain the error"]
        B3["Check if my service is properly connected to the pods"]
    end
    
    subgraph "Deployments & Configuration"
        C1["Deploy the Nginx Helm chart"]
        C2["Create a deployment with 3 replicas of nginx:latest"]
        C3["Set up an ingress for my service"]
    end
    
    subgraph "Advanced Operations"
        D1["Check the status of my Istio service mesh"]
        D2["Set up a canary deployment with 20% traffic to v2"]
        D3["Create an ArgoCD application for my repo"]
    end

Claude は依頼の意図を理解し、内容に応じて適切な kubectl、helm、istioctl、または argocd コマンドを実行できます。その後、出力をわかりやすく説明したり、問題のトラブルシューティングを支援したりできます。

Claude Desktop の高度な設定

Kubernetes のワークフローを最適化するために、Claude Desktop を設定します。

特定のクラスターと名前空間を指定する

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-e", "K8S_CONTEXT=production-cluster",
        "-e", "K8S_NAMESPACE=my-application",
        "-e", "K8S_MCP_TIMEOUT=600",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

AWS EKS クラスターに接続する

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro",
        "-e", "AWS_PROFILE=production",
        "-e", "AWS_REGION=us-west-2",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Google GKE クラスターに接続する

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.config/gcloud:/home/appuser/.config/gcloud:ro",
        "-e", "CLOUDSDK_CORE_PROJECT=my-gcp-project",
        "-e", "CLOUDSDK_COMPUTE_REGION=us-central1",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Azure AKS クラスターに接続する

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.azure:/home/appuser/.azure:ro",
        "-e", "AZURE_SUBSCRIPTION=my-subscription-id",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

許容的なセキュリティモード

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-e", "K8S_MCP_SECURITY_MODE=permissive",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

セキュリティ設定の詳細については、セキュリティドキュメントを参照してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。