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

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

現行版は実行時のフラグをほぼ廃止し、--toolsetsや--read-onlyといった設定をTOMLファイルに移しています。古い解説どおりにフラグを渡すと起動に失敗するので、この記事はTOML前提で手順を組んでいます。

マニフェストそのものをファイルとして書く作業は、Claude CodeでKubernetesマニフェストを書く手順で扱っています。既存リソースの操作ではなく、CRDとコントローラーを一から組み立てる場合はClaude CodeでKubebuilder Operatorを作る手順が参考になります。

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

同種のMCPサーバーの多くは内部でkubectlコマンドを組み立てて実行します。Kubernetes MCPサーバーはそれとは作りが違い、Kubernetes APIサーバーへ直接リクエストを投げます。ネイティブバイナリを使えばNodeやPythonのランタイムも不要で、Linux・macOS・Windows向けに配布されています。npmパッケージ、Pythonパッケージ、コンテナイメージでも入手できます。

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

古い手順で起動に失敗する理由 — 設定はTOMLに移った

現行版のCLIに残っているオプションは3つだけです。

ポート、kubeconfig、toolsets、読み取り専用モード、TLS、OAuthなどの実行時設定はすべてTOMLのキーです。削除されたフラグの置き換え先は次のとおりです。

削除済みのフラグをHelmチャートのextraArgsやコンテナのargsに残すと、cobraのunknown flagで失敗します。TOMLに存在しないキーを書いた場合も、ファイルの読み込みそのものが失敗します。

環境変数K8S_MCP_CONFIG_PATHもMCP_CONFIG_PATHに改名され、旧名は読まれません。移行期間や互換の仕組みもありません。ブログや古いREADMEのコピーでK8S_MCP_CONFIG_PATHを設定している場合は、ここが静かに効かなくなる原因になります。

移行時の落とし穴がもう1つあります。--disable-multi-clusterの移行先を書くときの注意です。cluster_provider_strategy = "kubeconfig"だけでkubeconfigを省くと、起動に失敗します。

Claude Codeに追加する

追加は3ステップです。読み取り専用で始める構成を例にします。

1つ目のステップは次のとおりです。

mkdir -p "$HOME/.config"
cat > "$HOME/.config/kubernetes-mcp-server.toml" <<'EOF'
read_only = true
EOF

2つ目のステップでMCPサーバーを登録します。-s userを付けると、すべてのプロジェクトで使えます。

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

Claude Code v2.1.289で、空の設定ディレクトリを使ってこの形のJSONを登録したところ、Added stdio MCP server kubernetes-mcp-server to user configと表示されました。ユーザースコープの設定ファイル(.claude.json)のmcpServersには、command・args・envが渡した値のまま保存されます。envを使うなら、JSONに"env":{"KUBECONFIG":"/path/to/kubeconfig"}を足します。

接続先クラスタは、TOMLのkubeconfigが空なら次の順で決まります。Pod内で動かしているときはクラスタ内の設定、そうでなければ$KUBECONFIG、それも無ければ~/.kube/configです。kubeconfigに空でないパスを書くと、クラスタ内の自動検出より優先されます。

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

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

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

ツールはtoolsetsという単位でグループ化されています。TOMLのtoolsetsの既定値は["core", "config"]で、基本操作とkubeconfig操作だけが有効です。

有効にする組はTOMLで指定します。Helmとの併用が多い開発環境なら、先ほどのファイルに1行足します。

read_only = true
toolsets = ["core", "config", "helm"]

使わないtoolsetを増やすほどツール定義が増え、モデルがどのツールを呼ぶべきか迷いやすくなります。公式READMEも、必要なtoolsetだけを有効にするとコンテキストが小さくなりツール選択の精度が上がると説明しています。KubeVirtやTektonを使わない環境ならcoreとconfigだけで十分です。

個別のツール単位で絞りたいときは、enabled_tools(許可リスト)とdisabled_toolsが使えます。toolsetを有効にしたまま、特定のツールだけ外す用途です。HTTPモードでは、kubeconfigの中身を返すconfiguration_viewツールが既定で無効になります。

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

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

デプロイの障害診断にも使えます。公開されているOpenShift環境のデモでは、Deploymentが起動失敗している原因をClaude Desktopが自力で切り分け、修正まで一貫して行っています。ゲーム開発を題材にしたデモでは、VS CodeでvibeコーディングしたコンテナをKubernetes MCPサーバー経由でOpenShiftにデプロイするところまで、会話の流れを切らずに進めています。

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

Kubernetes MCPサーバーは、個別ツールとは別に定型のプロンプトも提供します。coretoolsetのcluster-health-checkは、Namespaceを絞ることもクラスタ全体を見ることもでき、check_eventsで警告・エラーイベントを含めるかを選べます。

Claude CodeはMCPのプロンプトをコマンドとして扱います。/を入力すると/servername:promptname (MCP)の形で一覧に出て、/mcp__servername__promptnameと直接打っても実行できます。このサーバーをkubernetes-mcp-serverの名前で登録した場合は、/mcp__kubernetes-mcp-server__cluster-health-checkです。引数は空白区切りで後ろに続けます。毎回同じ調査手順を自然言語で説明し直す必要はありません。

他のtoolsetにも専用のプロンプトがあります。

• kiali: service-troubleshootはNamespaceとサービス名を渡すと、ログ・トレース・Istio設定を横断してエラーの原因を追います。trace-analysisは分散トレースから遅延やエラーの発生源を探します。istio-config-reviewは設定ミスの検出用です
• tekton: pipeline-troubleshootは、PipelineRunの状態、失敗したステップのログ、警告イベントをまとめて集めます
• kubevirt: vm-troubleshootが仮想マシンの診断手順を組み立てます

プロンプトはTOMLの[[prompts]]ブロックで自作もできます。{{pod_name}}のような引数付きのメッセージを定義すれば、チーム共通の調査手順を、コードを書かずに配れます。

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はmcp.jsonに、Claude Desktopと同じ形式のJSONブロックを書きます。CLIエージェントのGoose CLIではconfig.yamlのextensionsにcommand: npxと引数を書きます。どのクライアントでも、サーバー側の挙動を決めるのは--configで渡すTOMLなので、toolsetsやread_onlyの指定はそのまま流用できます。

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

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

MCPサーバーを大量に繋いでいる環境では、server_instructionsをTOMLに書いておくと役に立ちます。Claude CodeのMCP tool searchは既定で有効で、セッション開始時にはツール名とサーバーのinstructionsだけを読み込み、ツール定義は必要になるまで遅延させます。instructionsに「Kubernetesクラスタの管理タスク全般に使う」といった用途を書いておけば、どの場面でこのサーバーのツールを探すかをClaudeが判断しやすくなります。

server_instructions = """
Use this server for Kubernetes and OpenShift cluster management tasks:
pods, resources, namespaces, nodes, events, Helm releases.
"""

server_instructionsは、設定ファイルの再読み込み(SIGHUP)では反映されず、サーバーの再起動が必要なキーです。

書き込みを止める4つの設定

ここまでの手順は個人の開発クラスタを想定したものです。read_onlyの既定値はfalseなので、TOMLで何も指定しなければ書き込み・削除を含むツールがすべて使えます。しかも、渡したkubeconfigの権限がそのまま使われます。止める手段はTOMLに4種類あり、効く層が違います。

注意したいのはconfirmation_rulesです。確認プロンプトはMCPのelicitationで出すため、クライアントが対応していないと動作をconfirmation_fallbackが決めます。既定値は"allow"で、警告ログを残したまま確認なしで進みます。確認を出せないクライアントでは止めたい場合は、confirmation_fallback = "deny"に変えます。

confirmation_fallback = "deny"
 
[[confirmation_rules]]
tool = "helm_uninstall"
message = "This will uninstall a Helm release."

本番クラスタに繋ぐ場合は、TOMLの制限に加えて、専用のServiceAccountを読み取り専用のRBACロールに紐付ける構成が基本になります。サーバー側の設定はあくまで二重の備えで、権限そのものはKubernetesのRBACが決めます。具体的なServiceAccountの作り方とアクセス制御はKubernetes MCPサーバーの権限設計にまとめています。

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

よくあるつまずき

• npx実行のたびにダウンロードが走って遅い: @latestを固定バージョンに変えるか、リリースページからバイナリを落として./kubernetes-mcp-server --config <TOMLのパス>で直接起動すると解消します
• 複数クラスタのcontextを切り替えたい: multi-cluster対応は既定で有効です。ツール呼び出しにcontext引数を渡せば、kubeconfig内の別クラスタを指定できます。単一クラスタ運用に絞るなら、TOMLにcluster_provider_strategy = "disabled"を書きます
• OpenShift独自のツールが素のKubernetesで邪魔になる: projects_listのようなOpenShift専用ツールは、そのクラスタに存在しないAPIを前提にしています。TOMLにexperimental_enable_target_compatibility_tool_filters = trueを書くと、クラスタに無いAPIグループを必要とするツール(Metrics Serverが無い環境でのpods_topなど)が非表示になります。実験的なオプションです
• TOMLを直したのに反映されない: toolsetsやread_onlyなどはSIGHUPで再読み込みされますが、kubeconfig・cluster_provider_strategy・server_instructions・ポート類は再起動が必要です。stdioで起動している場合は、Claude Codeを再起動するか/mcpで再接続します

よくある質問

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

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

npxにはNode.jsが必要ですか。Windowsでは

npxで起動する以上、Node.jsとnpmは必要です。Node.jsを入れたくない環境では、Linux・macOS・Windows向けに配布されているネイティブバイナリを直接使います。設定の再読み込み(SIGHUP)はWindowsでは使えないため、TOMLを直したらプロセスを再起動します。

まとめ

古い手順のフラグ指定は動かないので、read_onlyとtoolsetsはTOMLに書きます。診断だけならread_only = trueとcoreの組み合わせで足り、Helmを使う場面でだけhelmを足す順で開けていけます。本番に繋ぐ前にServiceAccountとRBACを先に整えます。