mcp-kubernetes

mcp-kubernetes

Kubernetes 用の Model Context Protocol サーバーです。MCP 対応クライアント（Claude Desktop、Claude Code など）から、複数のコンテキストにまたがる Kubernetes クラスターを調査・操作できます。動作はすべてフラグで制御します。

設計目標はデフォルトで安全であることです。読み取り専用で起動し、許可リストによって名前空間とコンテキストを制限できます。また、システム名前空間を変更から保護し、危険な操作（削除、適用、実行）は明示的なオプトインを必須とします。

機能

• マルチクラスター — すべてのツールで context を任意で指定できます。許可リストを使って利用可能なコンテキストを制限できます。
• アクセスモード — read-only → read-write → admin の順に機能が追加され、各モードでそのレベルを超えるツールが公開されることはありません。
• セキュリティフラグ — 名前空間の許可リスト、保護対象の名前空間、コンテキストの許可リストに加え、削除／適用／実行の個別オプトイン、ドライラン、JSON 監査ログを設定できます（以下を参照）。
• 標準認証 — kube-config（またはクラスター内サービスアカウント）を使用します。サーバーに認証情報は保存されません。

セキュリティモデル

懸念事項	フラグ	デフォルト	効果
サーバーで実行できる操作は？	K8S_MODE	read-only	read-only では読み取り操作のみ、read-write では変更操作も可能になり、admin では破壊的なツールも追加されます。モードの範囲を超えるツールは登録されません。
対象となる名前空間は？	K8S_NAMESPACE_ALLOWLIST	(すべて)	設定すると、リスト外の名前空間に対する操作は拒否されます。
常に読み取り専用となる名前空間は？	K8S_PROTECTED_NAMESPACES	kube-system,kube-public,kube-node-lease	読み取りは可能ですが、モードにかかわらず変更や削除はできません。
接続可能なクラスターは？	K8S_CONTEXT_ALLOWLIST	(すべて)	設定すると、対象にできるのはこれらの kube-config コンテキストのみです。
削除を許可するか？	K8S_ALLOW_DELETE	false	delete_resource には、この設定と admin モードの両方が必要です。
マニフェストの適用を許可するか？	K8S_ALLOW_APPLY	false	apply_manifest には、この設定と read-write モードの両方が必要です。
Pod 内での exec を許可するか？	K8S_ALLOW_EXEC	false	exec_in_pod には、この設定と admin モードの両方が必要です。設定がない場合、このツール自体が登録されません。
クラスターに変更を加えずにプレビューする	K8S_DRY_RUN	false	書き込み／管理者向けツールは検証を行い、実行意図をログに記録した後、API を呼び出さずに返ります。
監査証跡	K8S_AUDIT_LOG	true	保護対象の操作ごとに、JSON の行を stderr に出力します（ALLOW／DENY／DRY_RUN）。
対話形式の確認	(自動)	—	破壊的な操作や影響の大きい操作を実行する前に、MCP elicitation を介して人間に承認を求めます。elicitation に対応していないクライアントでは、代わりに *_ALLOW_* の設定が適用されます。

各レイヤーは独立しています。たとえば、3 つのオプトインをすべて false にした admin モードでは、デプロイの再起動やスケーリングはできますが、リソースの削除や Pod 内での exec はできません。

ツール

読み取り（read-only以上）：list_contexts、list_namespaces、list_pods、get_pod、get_pod_logs、list_deployments、list_services、list_nodes、list_events、get_resource

書き込み（read-write以上）：scale_deployment、restart_deployment、set_deployment_image、create_namespace、apply_manifest（K8S_ALLOW_APPLYが必要）

管理者（admin）：delete_resource（K8S_ALLOW_DELETEが必要）、exec_in_pod（K8S_ALLOW_EXECが必要）

オプションのAIリスクガード。 K8S_GUARD_MODE=monitor|enforceを設定すると、delete_resource、exec_in_pod、apply_manifestの実行前に、ローカルのlaya-guardデーモン（pipx install laya-guard && laya-guard）で操作を許可／確認／ブロックに分類します。削除／実行／適用のゲートを通過した後に動作し、制限を強化することのみ可能で、許可を与えることはありません。障害時は安全側に倒して処理を拒否します。

クイックスタート — エージェントに追加する

npmで@dockndevai/mcp-kubernetesとして公開されています。クローンやビルドは不要です。MCPクライアントが必要に応じてnpxで実行します。まずはread-onlyモードで開始してください。すべての変数については.env.exampleを、クライアントごとの詳しいガイドについてはdocs/CLIENTS.mdを参照してください。

Claude Code（CLI）

claude mcp add kubernetes -e KUBECONFIG_PATH="/Users/you/.kube/config" -e K8S_MODE="read-only" -- npx -y @dockndevai/mcp-kubernetes

Claude Desktop · Cursor · Windsurf — 同じ設定ブロックをclaude_desktop_config.json、.cursor/mcp.json、または~/.codeium/windsurf/mcp_config.jsonに記述します：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.tomlに記述します：

[mcp_servers.kubernetes]
command = "npx"
args = ["-y", "@dockndevai/mcp-kubernetes"]
env = { KUBECONFIG_PATH = "/Users/you/.kube/config", K8S_MODE = "read-only" }

VS Code（GitHub Copilot、エージェントモード） — .vscode/mcp.jsonに記述します：

{
  "servers": {
    "kubernetes": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

ソースから実行する（開発）

上記の公開パッケージの利用をおすすめします。クローンから実行する場合：

npm install
npm run build
node dist/index.js   # with the environment variables set

開発

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

公開

このサーバーには、公式MCPレジストリ用のserver.jsonと、npmの所有権検証用のmcpNameが含まれています。npmへの公開と、MCPレジストリ、Smithery、Glama、Cursor、PulseMCPへの掲載については、**PUBLISHING.md**を参照してください。

ライセンス

MIT