Kubernetes Read Only MCP Server

mcp-k8s-ro

Claude から Kubernetes クラスターにアクセスできる、読み取り専用の MCP サーバーです。Go で構築されており、MCP プロトコルを使用して標準入出力経由で通信します。

設計

• 読み取り専用 — get、describe、logs、top 形式の操作のみを実行します。作成、更新、削除は行いません。変更を伴う操作が必要な場合は、手動で実行できる同等の kubectl コマンドをサーバーが出力します。夜間のオンコール中でも安心して使えます。プロンプト疲れが生じていても、Claude が誤ってクラスターを変更することはありません。
• シークレットを安全に保護 — シークレットの値はモデルに送信される前にマスキングされるため、設定ミスやプロンプトインジェクションによってシークレットが漏洩することはありません。
• トークン効率に優れる — 生の Kubernetes API オブジェクトではなく、関連するフィールド（名前、ステータス、再起動回数など）のみをレスポンスに含め、コンテキストの使用量を抑えます。
• クラスターを認識 — すべてのレスポンスに現在のコンテキストとクラスター名が含まれるため、Claude はどのクラスターとやり取りしているかを常に把握できます。
• コンテキストを固定 — サーバーは起動時にアクティブな kubeconfig コンテキストに固定されます。別のターミナルでコンテキストを切り替えても、実行中のサーバーには影響しません。
• 追加のインフラは不要 — ローカルバイナリまたは Docker コンテナとして実行され、起動時にアクティブな kubeconfig コンテキストに接続します。

マスキングされるフィールド

オブジェクト／フィールド	理由
Secret.data	シークレットの漏洩防止
Secret.stringData	シークレットの漏洩防止
CertificateSigningRequest.spec.request	大きな Base64 PEM データで、診断に役立つ情報がなく、トークンを節約できるため
Certificate (cert-manager) .spec.keystores	証明書チェーンの PEM データで、診断に役立つ情報がなく、トークンを節約できるため
Certificate (cert-manager) status.conditions[].message	証明書チェーンの PEM データで、診断に役立つ情報がなく、トークンを節約できるため
*.managedFields	診断に役立つ情報がなく、トークンを節約できるため

ツール

ツール	説明
k8s_list_resources	名前を指定して任意のリソースタイプ（ポッド、デプロイメント、CRD など）を一覧表示します。任意で名前空間による絞り込みを指定できます。リソースの種類に応じて、名前、ステータス、準備状況、再起動回数、ノード、IP などを返します。
k8s_describe_resource	単一リソースの完全な YAML を返します。シークレットのデータはマスクされます。
k8s_list_resource_types	検出 API を介して、利用可能なすべてのリソースタイプを一覧表示します。任意で API グループによる絞り込みを指定できます。
k8s_get_logs	ポッドのログを取得します。コンテナの選択、末尾の行数、およびクラッシュしたコンテナ用の --previous に対応しています。
k8s_get_events	名前空間またはクラスター全体の Kubernetes イベントを、最新のものから順に一覧表示します。
k8s_top_pods	ポッドごとの CPU とメモリの使用量を、コンテナごとの内訳とともに表示します。metrics-server が必要です。
k8s_top_nodes	ノードごとの CPU とメモリの使用量を、割り当て可能な容量に対する割合とともに表示します。metrics-server が必要です。

設定

環境変数	デフォルト値	説明
KUBECONFIG	~/.kube/config	kubeconfig ファイルのパス

Claude での使用方法

Docker（推奨）

claude mcp add --scope user --transport stdio k8s-ro \
  -- docker run --rm -i -v ~/.kube:/home/nonroot/.kube:ro ghcr.io/your-ko/mcp-k8s-ro:latest

本番環境での使用には、特定のバージョンを固定すること（最新リリース を確認してください）を推奨します。

claude mcp add --scope user --transport stdio k8s-ro \
  -- docker run --rm -i -v ~/.kube:/home/nonroot/.kube:ro ghcr.io/your-ko/mcp-k8s-ro:1.1.0

バイナリ

ビルド済みバイナリを GitHub Releases からダウンロードします。

# macOS Apple Silicon — change ARCH for other platforms: darwin-amd64, linux-amd64, linux-arm64
ARCH=darwin-arm64
VERSION=$(curl -fsSL https://api.github.com/repos/your-ko/mcp-k8s-ro/releases/latest | grep tag_name | cut -d'"' -f4)
curl -fsSL "https://github.com/your-ko/mcp-k8s-ro/releases/download/${VERSION}/mcp-k8s-ro-${VERSION}-${ARCH}" -o ~/.local/bin/mcp-k8s-ro
chmod +x ~/.local/bin/mcp-k8s-ro
xattr -d com.apple.quarantine ~/.local/bin/mcp-k8s-ro 2>/dev/null  # macOS only: remove Gatekeeper quarantine
claude mcp add --scope user --transport stdio k8s-ro ~/.local/bin/mcp-k8s-ro

macOS Gatekeeper：バイナリはコード署名されていないため、macOS によってブロックされます。 上記の xattr コマンドで隔離フラグを削除できます。または、初回にブロックされた後、システム設定 → プライバシーとセキュリティに移動し、「このまま開く」をクリックしてください。

または、ソースからビルドします。

make build
claude mcp add --scope user --transport stdio k8s-ro ./bin/mcp-k8s-ro

kubeconfig の場所を指定する

kubeconfig が ~/.kube/config にない場合は、KUBECONFIG 環境変数を設定します。

# Binary
claude mcp add --scope user --transport stdio -e KUBECONFIG=/path/to/kubeconfig k8s-ro ~/.local/bin/mcp-k8s-ro

# Docker
claude mcp add --scope user --transport stdio k8s-ro \
  -- docker run --rm -i -e KUBECONFIG=/config/kubeconfig -v /path/to/kubeconfig:/config/kubeconfig:ro ghcr.io/your-ko/mcp-k8s-ro:latest

単一クラスター設計

このサーバーは意図的に 1 つの kubeconfig コンテキストのみで動作し、実行時にクラスターを切り替えるツールは提供しません。その理由は次のとおりです。

• プロンプトインジェクションの分離 — あるクラスターのリソースに含まれる悪意のある値（ポッドのアノテーションなど）によって、Claude が本番環境を含む別のクラスターに移動するよう指示されることはありません。
• 明確な監査境界 — 各ツールの応答にはコンテキストとクラスター名が含まれるため、どのクラスターがクエリされたかが曖昧になることはありません。

サーバーの接続先を別のクラスターに変更するには、サーバーを停止し、コンテキストを切り替えてから再起動します。

kubectl config use-context my-other-cluster
# then restart the MCP server / reload Claude Desktop

複数のクラスターを同時に操作するには、MCP 設定でクラスターごとに別々のサーバーインスタンスを登録します。

{
  "mcpServers": {
    "k8s-staging": {
      "type": "stdio",
      "command": "/path/to/bin/mcp-k8s-ro",
      "env": { "KUBECONFIG": "/path/to/.kube/config" }
    },
    "k8s-prod": {
      "type": "stdio",
      "command": "/path/to/bin/mcp-k8s-ro",
      "env": { "KUBECONFIG": "/path/to/.kube/config-prod" }
    }
  }
}

Claude はサーバーをそれぞれの名前で指定し、各インスタンスが認識するのは自身のクラスターのみです。

MCP レジストリ

このサーバーは registry.modelcontextprotocol.io で公開されています。