MCP Server Kubernetes

MCP Server Kubernetes

Kubernetes クラスターに接続して管理できる MCP サーバーです。優先順位に従って、複数のソースから kubeconfig を読み込めます。

https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed

インストールと使い方

前提条件

この MCP サーバーを任意のツールで使用する前に、以下を確認してください。

1. kubectl がインストールされ、PATH に設定されていること
2. コンテキストが設定された有効な kubeconfig ファイルがあること
3. kubectl 用に設定された Kubernetes クラスター（minikube、Rancher Desktop、GKE など）にアクセスできること
4. Helm v3 がインストールされ、PATH に設定されていること（Tiller は不要）。Helm を使用する予定がない場合は任意です。

ターミナルで kubectl get pods を実行し、認証情報の問題なくクラスターに接続できることを確認できます。

デフォルトでは、サーバーは ~/.kube/config から kubeconfig を読み込みます。追加の認証オプション（環境変数、カスタムパスなど）については、ADVANCED_README.md を参照してください。

Claude Code

組み込みコマンドを使用して、MCP サーバーを Claude Code に追加します。

claude mcp add kubernetes -- npx mcp-server-kubernetes

これにより、Claude Code の MCP 設定でサーバーが自動的に構成されます。

Codex

組み込みコマンドを使用して、MCP サーバーを Codex CLI に追加します。

codex mcp add kubernetes -- npx mcp-server-kubernetes

これにより、サーバーが ~/.codex/config.toml にグローバル登録され、すべての Codex セッションでそのツールを利用できるようになります。

Claude Desktop

以下の設定を Claude Desktop の設定ファイルに追加します。

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

mcpb による Claude Desktop Connector

MCP Server Kubernetes は、mcpb（旧称 dxt）拡張機能としても利用できます。Claude Desktop で Settings（Mac では Cmd+,）-> Extensions -> Browse Extensions の順に移動し、モーダル内で mcp-server-kubernetes を見つけてください。インストールすると、コマンドライン経由で kubectl をインストールして使用し、kubeconfig を利用します。

手動でインストールする場合は、最新の Release にアクセスして .mcpb をダウンロードすることもできます。

VS Code

VS Code は MCP を標準でサポートしています。上のワンクリックインストールボタンを使用するか、ワークスペースの .vscode/mcp.json（または MCP: Open User Configuration からユーザーの mcp.json）にサーバーを追加してください。

{
  "servers": {
    "kubernetes": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

Cursor

Cursor は AI 統合を通じて MCP サーバーをサポートしています。サーバーを ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に追加します：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

サーバーは現在の kubectl コンテキストに自動的に接続します。AI アシスタントにポッドの一覧表示やテスト用デプロイメントの作成を依頼して、接続を確認できます。

Muse Code

Muse Code は、~/.config/muse/settings.json の mcp_servers ブロックから MCP サーバーを読み込みます。ファイルには "schema_version": 1 を含める必要があります：

{
  "schema_version": 1,
  "mcp_servers": {
    "kubernetes": {
      "transport": "stdio",
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

代わりに Streamable HTTP 経由で接続するには、まずサーバーを HTTP モードで起動します（デフォルトではポート 3000 で /mcp を提供します。Streamable HTTP Transport を参照してください）：

ENABLE_UNSAFE_STREAMABLE_HTTP_TRANSPORT=1 npx mcp-server-kubernetes

次に、streamable_http トランスポートを使用して、Muse Code の接続先にそのエンドポイントを指定します（headers は任意です）：

{
  "schema_version": 1,
  "mcp_servers": {
    "kubernetes": {
      "transport": "streamable_http",
      "url": "http://localhost:3000/mcp",
      "mode": "optional"
    }
  }
}

"mode": "optional" を指定すると、HTTP サーバーが起動していない場合でも処理を中断せず、警告を表示して Muse Code を起動できます。

ファイルを編集したら、新しい Muse Code セッションを開始し、/mcp を実行して kubernetes サーバーとそのツールが接続されていることを確認します。

mcp-chat の使用方法

mcp-chat は、MCP サーバー向けの CLI チャットクライアントです。これを使用して Kubernetes サーバーとやり取りできます。

npx mcp-chat --server "npx mcp-server-kubernetes"

または、上記の既存の Claude Desktop 設定ファイルを渡します（Linux では、正しい設定ファイルのパスを指定してください）：

Mac：

npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"

Windows：

npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"

機能

• Kubernetes クラスターに接続
• リソースを管理するための統合 kubectl API
  • kubectl_get でリソースを取得または一覧表示
  • kubectl_describe でリソースを説明
  • kubectl_get でリソースを一覧表示
  • kubectl_create でリソースを作成
  • kubectl_apply で YAML マニフェストを適用
  • kubectl_delete でリソースを削除
  • kubectl_logs でログを取得
  • kubectl_context で kubectl コンテキストを管理
  • explain_resource で Kubernetes リソースを説明
  • list_api_resources で API リソースを一覧表示
  • kubectl_scale でリソースをスケーリング
  • kubectl_patch でリソースのフィールドを更新
  • kubectl_rollout でデプロイメントのロールアウトを管理
  • kubectl_generic で任意の kubectl コマンドを実行
  • ping で接続を確認
• 高度な操作
  • kubectl_scale でデプロイメントをスケーリング（従来の scale_deployment を置き換え）
  • port_forward でポッドやサービスにポートフォワード
  • Helm 操作を実行
    • チャートのインストール、アップグレード、アンインストール
    • カスタム値、リポジトリ、バージョンをサポート
    • 認証の問題を回避するテンプレートベースのインストール（helm_template_apply）
    • 認証の問題を回避するテンプレートベースのアンインストール（helm_template_uninstall）
  • ポッドのクリーンアップ操作
    • Evicted、ContainerStatusUnknown、Completed、Error、ImagePullBackOff、CrashLoopBackOff 状態の問題のあるポッドをクリーンアップ（cleanup_pods）
  • ノード管理操作
    • メンテナンスやスケーリング操作のためにノードをコーディング、ドレイン、コーディング解除（node_management）
• トラブルシューティングプロンプト（k8s-diagnose）
  • キーワードと任意の名前空間に基づき、ポッドの体系的な Kubernetes トラブルシューティング手順を案内します。
• クラスターへの読み取りおよび作成・更新のみのアクセスを許可する非破壊モード
• セキュリティのためのシークレットのマスキング（kubectl get secrets コマンド内の機密データをマスキングします。ログには影響しません）
• OpenTelemetry による可観測性（オプトイン）
  • すべてのツール呼び出しを分散トレース
  • Jaeger、Tempo、Grafana、または任意の OTLP バックエンドへのエクスポート
  • サンプリング戦略を設定可能
  • 詳細なスパン属性（ツール名、所要時間、K8s コンテキスト、エラー）
  • 詳細は docs/OBSERVABILITY.md を参照してください

可観測性

MCP Kubernetes サーバーには、包括的な可観測性を実現するためのオプションの OpenTelemetry 統合が含まれています。この機能はデフォルトで無効になっており、環境変数または Helm 設定で有効にできます。

クイックスタート

環境変数を使って可観測性を有効にします。

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

npx mcp-server-kubernetes

トレースの対象

• すべてのツール呼び出し：kubectl_get、kubectl_apply、kubectl_logs など
• 実行時間：各操作にかかる時間
• 成功／失敗の状態：エラーを自動的に追跡します
• Kubernetes コンテキスト：名前空間、コンテキスト、リソースの種類
• 豊富なメタデータ：ホスト、プロセス、カスタム属性

対応バックエンド

OTLP 互換のバックエンドであれば、どれでも動作します。

• Jaeger（オープンソース）
• Grafana Tempo（オープンソース）
• Grafana Cloud（商用）
• Datadog、New Relic、Honeycomb、Lightstep、AWS X-Ray

設定

以下を含む包括的なドキュメントについては、docs/OBSERVABILITY.md を参照してください。

• 設定オプション
• デプロイ例（Kubernetes、Helm、Claude Code）
• サンプリング戦略
• 本番環境でのベストプラクティス
• トラブルシューティングガイド

Jaeger を使った例

# Start Jaeger
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Enable telemetry
export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_TRACES_SAMPLER=always_on

# Run server
npx mcp-server-kubernetes

# View traces: http://localhost:16686

プロンプト

MCP Kubernetes サーバーには、一般的な診断操作を支援する専用のプロンプトが含まれています。

/k8s-diagnose プロンプト

このプロンプトは、Kubernetes ポッドの体系的なトラブルシューティング手順を提供します。関連するポッドを特定するための keyword と、検索範囲を絞り込むための任意の namespace を指定できます。 プロンプトの出力では、自律的なトラブルシューティング手順を案内し、問題の特定、証拠の収集、修正手順の提案について説明します。

ローカル開発

Bun のインストールが完了していることを確認してください。リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
bun install

開発ワークフロー

1. 開発モードでサーバーを起動します（ファイルの変更を監視します）。

bun run dev

2. 単体テストを実行します。

bun run test

3. プロジェクトをビルドします。

bun run build

4. Inspector を使ったローカルテスト

npx @modelcontextprotocol/inspector node dist/index.js
# Follow further instructions on terminal for Inspector link

5. Claude Desktop を使ったローカルテスト

{
  "mcpServers": {
    "mcp-server-kubernetes": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
    }
  }
}

6. mcp-chat を使ったローカルテスト

bun run chat

コントリビューション

詳細については、CONTRIBUTING.md ファイルを参照してください。

詳細情報

非破壊モード

サーバーを非破壊モードで実行すると、破壊的な操作（ポッド、デプロイメント、名前空間の削除など）をすべて無効にできます。

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx mcp-server-kubernetes

非破壊モードを有効にした Claude Desktop の設定：

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

非破壊モードで使用できるコマンド

読み取り専用の操作と、リソースの作成／更新操作はすべて引き続き使用できます。

• リソース情報：kubectl_get、kubectl_describe、kubectl_logs、explain_resource、list_api_resources
• リソースの作成／変更：kubectl_apply、kubectl_create、kubectl_scale、kubectl_patch、kubectl_rollout
• Helm 操作：install_helm_chart、upgrade_helm_chart、helm_template_apply、helm_template_uninstall
• 接続：port_forward、stop_port_forward
• コンテキスト管理：kubectl_context

非破壊モードで無効になるコマンド

以下の破壊的な操作は無効になります。

• kubectl_delete：あらゆる Kubernetes リソースの削除
• uninstall_helm_chart：Helm チャートのアンインストール
• cleanup：管理対象リソースのクリーンアップ
• cleanup_pods：問題のあるポッドのクリーンアップ
• node_management：ノード管理操作（ノードのドレインが可能です）
• kubectl_generic：kubectl コマンドへの汎用アクセス（破壊的な操作を含む場合があります）
• exec_in_pod：ポッド内での任意のコマンド実行（サービスアカウントトークンの読み取りや状態の変更が可能です）

その他の高度な機能については、ADVANCED_README.md と、helm_install、helm_template_apply、ノード管理、ポッドのクリーンアップに関する詳細情報が記載された docs フォルダーを参照してください。

アーキテクチャ

Devin が作成した、より詳細なアーキテクチャの概要については、DeepWiki のリンクを参照してください。

このセクションでは、MCP Kubernetes サーバーの全体的なアーキテクチャについて説明します。

リクエストのフロー

以下のシーケンス図は、リクエストがシステム内をどのように流れるかを示しています。

sequenceDiagram
    participant Client
    participant Transport as Transport Layer
    participant Server as MCP Server
    participant Filter as Tool Filter
    participant Handler as Request Handler
    participant K8sManager as KubernetesManager
    participant K8s as Kubernetes API

    Note over Transport: StdioTransport or<br>SSE Transport

    Client->>Transport: Send Request
    Transport->>Server: Forward Request

    alt Tools Request
        Server->>Filter: Filter available tools
        Note over Filter: Remove destructive tools<br>if in non-destructive mode
        Filter->>Handler: Route to tools handler

        alt kubectl operations
            Handler->>K8sManager: Execute kubectl operation
            K8sManager->>K8s: Make API call
        else Helm operations
            Handler->>K8sManager: Execute Helm operation
            K8sManager->>K8s: Make API call
        else Port Forward operations
            Handler->>K8sManager: Set up port forwarding
            K8sManager->>K8s: Make API call
        end

        K8s-->>K8sManager: Return result
        K8sManager-->>Handler: Process response
        Handler-->>Server: Return tool result
    else Resource Request
        Server->>Handler: Route to resource handler
        Handler->>K8sManager: Get resource data
        K8sManager->>K8s: Query API
        K8s-->>K8sManager: Return data
        K8sManager-->>Handler: Format response
        Handler-->>Server: Return resource data
    end

    Server-->>Transport: Send Response
    Transport-->>Client: Return Final Response

Devin が作成した、より詳細なアーキテクチャの概要については、こちらのDeepWikiリンクをご覧ください。

新しいリリースの公開

リリースページに移動し、「Draft New Release」をクリックしてから、「Choose a tag」をクリックします。「v{major}.{minor}.{patch}」形式のセマンティックバージョニングで新しいバージョン番号を入力し、新しいタグを作成してください。次に、リリースタイトル「Release v{major}.{minor}.{patch}」と、必要に応じて説明または変更履歴を記入し、「Publish Release」をクリックします。

これにより新しいタグが作成され、cd.yml ワークフローによる新しいリリースビルドが開始されます。ビルドが成功すると、新しいリリースがnpmに公開されます。ワークフローが package.json ファイル内のバージョン番号を自動的に更新し、main にコミットをプッシュするため、package.json のバージョンを手動で更新する必要はありません。

予定していない機能

kubectx へのクラスターの追加。

スター履歴

🖊️ 引用

このリポジトリが役に立った場合は、以下を引用してください。

@software{Patel_MCP_Server_Kubernetes_2024,
author = {Patel, Paras and Sonwalkar, Suyog},
month = jul,
title = {{MCP Server Kubernetes}},
url = {https://github.com/Flux159/mcp-server-kubernetes},
version = {2.5.0},
year = {2024}
}