Kubernetes MCPサーバーでClaudeからクラスタを操作する

Kubernetes MCPサーバー(containers/kubernetes-mcp-server)は、kubectlやhelmをラップするのではなくKubernetes APIサーバーに直接つながるGoのネイティブ実装です。単一バイナリで動き、Claude Codeからは自然言語でPodのログ確認やHelmリリースの操作までこなせます。

Kubernetes MCPサーバーとは — kubectl/helmのラッパーではない

同種のMCPサーバーの多くは内部でkubectlコマンドを組み立てて実行します。Kubernetes MCPサーバーはそれとは作りが違い、Kubernetes APIサーバーへ直接リクエストを投げます。NodeやPythonのランタイムも不要で、Linux・macOS・Windows向けの単一バイナリとして配布されます。

対応範囲はKubernetes本体だけではありません。OpenShiftのProjects、Helmチャートのインストールと削除、Tektonのパイプライン操作、そしてIstio/Kialiのオブザーバビリティ機能まで、1つのMCPサーバーでカバーします。Helm・Istio・Kiali・KubeVirt・NetObserv・Tektonの各プロジェクトは自動評価シナリオで動作確認済みです。

Claude CodeにKubernetes MCPサーバーを追加する

npxが使える環境なら、claude mcp add-jsonコマンド1つで追加できます。

claude mcp add-json kubernetes-mcp-server \
  '{"command":"npx","args":["-y","kubernetes-mcp-server@latest"]}' \
  -s user

-s userを付けると、すべてのプロジェクトでこのMCPサーバーが使えるようになります。接続確認はclaude mcp listで行います。

claude mcp list

kubernetes-mcp-server: npx -y kubernetes-mcp-server@latest - ✓ Connectedと表示されれば接続完了です。接続先クラスタは~/.kube/config(または--kubeconfigで指定したファイル)のcurrent-contextが使われます。

Claude Desktopでも設定は同じ形です。claude_desktop_config.jsonのmcpServersに次のブロックを追加します。

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

提供ツールとtoolsetsで絞り込む

ツールはtoolsetsという単位でグループ化されています。既定で有効なのはcore(Pod・汎用リソース・イベントなどの基本操作)とconfig(kubeconfigの参照・切り替え)の2つです。

--toolsetsフラグで有効にする組を指定します。Helmとの併用が多い開発環境なら次のように起動します。

npx kubernetes-mcp-server@latest --toolsets core,config,helm

使わないtoolsetを増やすほどツール定義がコンテキストを圧迫し、モデルがどのツールを呼ぶべきか迷いやすくなります。KubeVirtやTektonを使わない環境ならcoreとconfigだけで十分です。

実際にクラスタを操作してみる

接続後は自然言語でクラスタの状態を聞けます。「クラスタの全Namespaceを一覧して」と指示すると、Claude CodeがKubernetes MCPサーバー経由でAPIサーバーに問い合わせ、結果を要約して返します。Podのログ確認・Exec実行・Helmリリースの一覧取得も同じ流れです。

デプロイの障害診断にも使えます。あるOpenShift環境のデモでは、Deploymentが起動失敗している原因をClaude Desktopが自力で切り分け、修正まで一貫して行っています。人手を介さずに「Podが立ち上がらない理由を調べて直して」という指示だけで完結する運用です。ゲーム開発を題材にしたデモでは、VS CodeでvibeコーディングしたコンテナをKubernetes MCPサーバー経由でそのままOpenShiftにデプロイするところまで、会話の流れを切らずに進めています。

組み込みプロンプトでクラスタの健全性チェックを実行する

Kubernetes MCPサーバーは、個別ツールとは別に定型のプロンプトも提供します。coretoolsetにはcluster-health-checkがあり、Namespace単位で警告・エラーイベントを含めた総合的な健全性評価を1回の呼び出しで実行できます。Claude Code上ではMCPのプロンプトはスラッシュコマンドとして扱われるため、毎回同じ調査手順を自然言語で説明し直す必要がありません。

kialitoolsetを有効にしていれば、service-troubleshootやtrace-analysisのようなIstioメッシュ特化のプロンプトも使えます。service-troubleshootはNamespaceとサービス名を渡すだけで、ログ・トレース・Istio設定を横断してエラーの原因を追跡します。tektontoolsetのpipeline-troubleshootは、PipelineRunのステータスから失敗したステップのログ、関連する警告イベントまでを1回でまとめて取得します。個別ツールを都度組み合わせるより、障害調査のような定型作業ではプロンプトを起点にする方が速く始められます。

VS Code・Cursorなど他クライアントでの追加方法

MCPサーバーとしての実装は共通なので、Claude Code以外のクライアントにも同じ設定を持ち込めます。VS Code(Insiders含む)はcode --add-mcpコマンドで追加できます。

code --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'

Cursorは.cursor/mcp.jsonに、Claude Desktopと同じ形式のJSONブロックを書きます。CLIエージェントのGoose CLIでもconfig.yamlのextensionsにコマンドを1行追加するだけで動きます。設定の中身自体はどのクライアントでも変わらないので、ここまでの--toolsetsや--read-onlyの指定はそのまま流用できます。

MCPログとサーバー起動時のヒント

Kubernetes MCPサーバーはMCPのlogging機能に対応しており、クライアント側にデバッグ情報を構造化ログとして送れます。トークンやパスワード、クラウド認証情報のようなセンシティブなデータは、クライアントに送る前に自動でマスクされる仕様です。Kubernetes APIのエラーも重要度別に自動分類され、クライアント側でどのログを優先して見るべきかが分かりやすくなります。

MCPサーバーを大量に繋いでいる環境では、server_instructionsをTOML設定に書いておくと、Claude Code側のMCP Tool Searchがこのサーバーのツールをいつ使うべきか判断しやすくなります。「Kubernetesクラスタの管理タスク全般に使う」といった1文を添えるだけで、関係のない場面での誤呼び出しを減らせます。

本番クラスタでは読み取り専用の権限設計が必要になる

ここまでの手順は個人の開発クラスタを想定したものです。既定の設定では、書き込み・削除を含むあらゆる操作が許可され、しかも自分のadmin権限のkubeconfigがそのまま渡ります。

本番クラスタに繋ぐ場合は話が変わります。専用のServiceAccountを読み取り専用のRBACロールに紐付け、--read-onlyフラグと組み合わせるのが最低ラインです。具体的なServiceAccountの作り方とTOML設定でのアクセス制御はKubernetes MCPサーバーの権限設計にまとめています。

Kubernetes MCPサーバーの使い分け早見表

よくあるつまずき

• npx実行のたびにダウンロードが走って遅い: @latestを固定バージョンに変えるか、リリースページからバイナリを落として./kubernetes-mcp-serverで直接起動すると解消します
• 複数クラスタのcontextを切り替えたい: multi-cluster対応は既定で有効です。ツール呼び出しにcontext引数を渡せば、kubeconfig内の別クラスタを指定できます。単一クラスタ運用に絞るなら--disable-multi-clusterで無効化できます
• OpenShift独自のツールが動かない: projects_listのようなOpenShift専用ツールは、接続先がOpenShiftでないと機能しません。素のKubernetesクラスタでは表示されても失敗します
• HelmリリースがToolset未有効で見えない: helmは既定で無効です。--toolsetsに明示的に含めるか、TOML設定のtoolsets配列に追加してください

よくある質問

Kubernetes MCPサーバーはAnthropic公式のプロダクトですか

いいえ。containersorg配下でメンテナンスされているOSSで、Anthropicの公式サーバーではありません。Claude Codeの一般的なMCP追加手順(claude mcp add-json)で繋げる、サードパーティ製のMCPサーバーの1つです。MCPサーバー追加コマンドの構文やスコープの使い分けそのものはClaude Code MCP設定ガイドにまとめています。

npxとネイティブバイナリ、どちらを使うべきですか

CI環境や起動速度を重視するなら、リリースページの単一バイナリを直接使う方が安定します。ローカルでの試行錯誤段階なら、常に最新版を取得できるnpxが手軽です。

GitHub MCPサーバーなど他のMCPサーバーと同時に使えますか

問題なく併用できます。使わないtoolsetsを絞ってコンテキストを軽くしておけば、複数のMCPサーバーを繋いでもツール選択の精度は落ちにくくなります。

Windows環境でも同じ手順で動きますか

動きます。Linux・macOS・Windows向けにそれぞれ単一バイナリが配布されており、npx経由でもOSを問わず同じコマンドで起動できます。WindowsだけNodeやPythonの追加インストールが必要になる、といった差はありません。

まとめ

Kubernetes MCPサーバーはkubectlのラッパーではなく、APIサーバーに直接つながる単一バイナリです。まずはclaude mcp add-jsonで個人クラスタに繋いで挙動を確かめ、使わないtoolsetsは外してコンテキストを軽くします。本番クラスタに繋ぐ前には、読み取り専用のServiceAccountとRBAC設計を先に済ませてください。