k8scortex-mcp

K8sCortex — Kubernetes MCP サーバー

セキュリティチームが承認できる Kubernetes アクセスを AI エージェントに提供します。 K8sCortex は、GKE、EKS、AKS、OpenShift、ローカルクラスター向けの統制された MCP ゲートウェイです。すべてのリクエストで SSO を適用し、ロール階層、クラスターごとのポリシー、デフォルトのドライラン、誰が何を要求したかを記録する監査ログを備えています。

多くの Kubernetes MCP サーバーは、エージェントに kubeconfig を渡します。K8sCortex はその間に入り、担当者とクラスターごとに、75 個のツールのうちどれを実行できるかを判断し、すべての呼び出しを記録します。異なるクラウドのクラスターを 1 つのレジストリで管理し、必要に応じて認証情報を発行します。

_{K8sCortex のみをツールとして使用し、使い捨ての本番クラスターで実行した、実際の Claude Code セッションです。開発者はロールバックを拒否され、リリースマネージャーは本番環境のポリシーによってブロックされ、SRE が問題を修正します。 5 つのシナリオをすべて見る（97 秒）：インシデント、リリースのドリフト、フラッシュセール時のスケーリング、パスワードのローテーション、ノードのメンテナンス。記録方法。}

---

機能

• 複数のドメインを網羅する厳選されたツールセット。ワークロード、デプロイ、構成、可観測性、ジョブ、ネットワーキング、GitOps、クラスター管理、汎用の読み取りパスを網羅します
• マルチクラウドのクラスター プロバイダー — kubeconfig コンテキスト、Amazon EKS（IAM/IRSA）、Google GKE（Workload Identity）、Azure Key Vault を 1 つのレジストリで混在させて管理できます
• マルチクラスターのルーティング — 単一の cluster パラメーターで登録済みの任意のクラスターを指定できます。複数のクラスターが登録されている場合、書き込みには明示的なクラスター指定が必要です
• あらゆる OIDC ID プロバイダー（Entra ID、Okta、Cognito、Keycloak、Google）に対応し、ツールごとの RBAC（5 段階のロール階層）とクラスターごとのポリシーを適用します
• 構造化された監査ログ — 呼び出し元の ID、引数、結果とともに、すべてのツール呼び出しを記録します
• デュアルトランスポート — プログラムから利用するクライアント向けの SSE/HTTP と、Claude Desktop 向けの stdio
• 有効期間の短い認証情報 — EKS と GKE のトークンを必要に応じて発行し、有効期限までに限ってキャッシュします
• ドライランによる安全性 — 破壊的なツールはデフォルトでシミュレーションモードになります
• 汎用の読み取り範囲 — 厳選された書き込みパスの対象外にあるリソースも list/get でサポートし、トラブルシューティングが行き詰まるのを防ぎます

インストール

Claude Desktop、Claude Code、Cursor などの MCP クライアント（stdio）

Node.js 22 以降と、正常に動作する kubeconfig が必要です。クライアントの MCP 設定に追加してください（Claude Desktop の場合は claude_desktop_config.json）。

{
  "mcpServers": {
    "k8scortex": {
      "command": "npx",
      "args": ["-y", "k8scortex-mcp"],
      "env": { "K8SCORTEX_STDIO_ROLES": "developer" }
    }
  }
}

developer では読み取り専用のセッションになります。すべてのツールを使用するには、これを削除してください。Claude Code の場合は、claude mcp add k8scortex -- npx -y k8scortex-mcp を実行します。

チーム向けの共有サービスとして（HTTP + OIDC）

Helm チャートを使用します（デフォルトは読み取り専用の RBAC です。書き込み権限やその他のクラウドについては、チャートの README を参照してください）。

helm install k8scortex ./charts/k8scortex -n platform-mcp --create-namespace \
  --set auth.oidc.issuer=https://login.example.com --set auth.oidc.audience=k8scortex

チャートからレンダリングしたプレーンなマニフェストは kubernetes/ にあります。または、イメージを直接実行します。

docker run -p 3000:3000 \
  -e OIDC_ISSUER=https://login.example.com -e OIDC_AUDIENCE=k8scortex \
  -e CLUSTERS_CONFIG=/config/clusters.json -v "$PWD/clusters.json:/config/clusters.json:ro" \
  ghcr.io/apatilgtn/k8scortex-mcp:latest

クラウドプロバイダー向けの Workload Identity／IRSA／マネージド ID を設定した管理クラスターで実行し、内部向けに /mcp を公開して、監査ログを SIEM に送信してください。マルチクラウドのセットアップと認証を参照してください。

開発

前提条件

• Node.js ≥ 22（GKE プロバイダーの google-auth-library と、jwks-rsa の依存関係である jose に必要です）
• Kubernetes クラスター（minikube、kind、GKE、EKS、AKS、または OpenShift）
• 有効なコンテキストで設定された kubectl

インストールと実行

# Clone
git clone https://github.com/apatilgtn/k8scortex-mcp.git
cd k8scortex-mcp

# Install
npm install

# Build
npm run build

# Run (local dev mode — auth bypassed)
DISABLE_AUTH=true PORT=3001 npm run dev

MCP Inspector に接続する

npx @modelcontextprotocol/inspector sse http://localhost:3001/mcp

Claude Desktop をローカルビルドに接続する

npm パッケージではなく、ビルドしたものをクライアントに指定します。

{
  "mcpServers": {
    "k8scortex": {
      "command": "node",
      "args": ["<path-to>/k8scortex-mcp/dist/stdio.js"]
    }
  }
}

Claude Desktop を再起動します。「デフォルトの名前空間にあるすべてのポッドを一覧表示して」と尋ねてください。

kubeconfig 内のすべてのコンテキストをクラスターとして利用できるため、「kind-dev と prod-eks の間で、web app の ArgoCD リビジョンを比較して」と尋ねることができます。K8SCORTEX_STDIO_ROLES=developer を設定すると、ローカルセッションに読み取り専用ツールが付与されます。

---

マルチクラウドのセットアップ

K8sCortex は、環境に応じてクラスターの情報源を選択します。

情報源	条件	クラスター
CLUSTERS_CONFIG=/path/clusters.json	設定されている場合	任意のプロバイダーにまたがる、ファイルに記載されたクラスター
Azure Key Vault	AZURE_KEYVAULT_URI が設定されている場合	Key Vault のクラスターインデックス
kubeconfig	上記以外（または USE_LOCAL_KUBECONFIG=true の場合）	KUBECONFIG / ~/.kube/config 内のすべてのコンテキスト、またはクラスター内のサービスアカウント

DEFAULT_CLUSTER は、ツール呼び出しでクラスターが指定されなかった場合に使用するクラスターを選択します。読み取り専用ツールではこのクラスターが既定で使用されます。変更を伴うツールでは、複数のクラスターが登録されている場合、cluster の明示的な指定が必要です。

クラスター登録ファイル

{
  "defaultCluster": "dev",
  "clusters": [
    { "name": "dev", "provider": "kubeconfig", "context": "kind-dev", "labels": { "env": "dev" } },
    { "name": "prod-eks", "provider": "eks", "region": "us-east-1", "eksClusterName": "prod",
      "roleArn": "arn:aws:iam::111122223333:role/k8scortex", "labels": { "env": "prod" } },
    { "name": "prod-gke", "provider": "gke", "project": "my-project", "location": "us-central1",
      "gkeClusterName": "prod", "labels": { "env": "prod" } },
    { "name": "prod-aks", "provider": "azure-keyvault", "cloud": "aks", "region": "australiaeast",
      "keyVaultUri": "https://my-vault.vault.azure.net", "labels": { "env": "prod" } }
  ],
  "policies": [
    { "labels": { "env": "prod" }, "minRole": "sre", "appliesTo": "mutating" },
    { "match": "prod-*", "denyTools": ["drain_node", "delete_namespace"] }
  ]
}

プロバイダー	認証情報	フィールド
kubeconfig	コンテキストが使用する認証情報（exec プラグイン（aws eks get-token、gke-gcloud-auth-plugin、kubelogin）を含む）	context、kubeconfigPath
eks	既定の AWS 認証情報チェーン（IRSA、EKS Pod Identity、インスタンスプロファイル、環境変数、SSO）。オプションで roleArn を使用してロールを引き受けます。トークンは 14 分ごとに更新される、署名付き STS URL です	region、eksClusterName、roleArn
gke	アプリケーションのデフォルト認証情報（GKE Workload Identity、サービスアカウント、gcloud auth application-default login）	project、location、gkeClusterName、usePrivateEndpoint
azure-keyvault	マネージド ID。シークレット kubeconfig-<name> 内の base64 エンコードされた kubeconfig（または secretName）	keyVaultUri、secretName

EKS および GKE プロバイダーはオプションの依存関係（@aws-sdk/client-eks、@aws-sdk/credential-providers、@smithy/signature-v4、@aws-crypto/sha256-js、google-auth-library）を使用します。これらは npm によってデフォルトでインストールされます。ID には、EKS では eks:DescribeCluster と EKS アクセスエントリが、GKE では container.clusters.get と Kubernetes RBAC が必要です。

クラスターごとのポリシー

ポリシーは、クラスター名のグロブ（match）および／または labels でクラスターを照合し、グローバルなロールテーブルを厳格化することのみができます。

• minRole は、該当するクラスターで必要なロールを引き上げます（appliesTo: "mutating" を指定すると、書き込みツールに限定されます）
• denyTools は、該当するクラスターですべてのユーザーに対してツールを無効にします

compare_clusters は、読み取り対象となる両方のクラスターに対してチェックされます。

認証

HTTP モードは、ID プロバイダーが設定されていない場合（または DISABLE_AUTH=true の場合）、起動を拒否します。

変数	説明
OIDC_ISSUER	発行者 URL（カンマ区切り）。JWKS は /.well-known/openid-configuration から検出されます
OIDC_AUDIENCE	期待するオーディエンス（カンマ区切り）
OIDC_JWKS_URI	オプションの JWKS URL 上書き
OIDC_ROLES_CLAIM	ロール／グループを格納するクレーム（デフォルトは roles。例：groups、cognito:groups、realm_access.roles）
OIDC_ROLE_MAP	IdP グループ名から K8sCortex のロールへの JSON マッピング。例：{"k8s-admins":"platform-engineer"}
ENTRA_TENANT_ID / ENTRA_CLIENT_ID	Entra ID 用の簡易設定（発行者、オーディエンス、JWKS を設定します）

---

ツール

K8sCortex は、柔軟な読み取りアクセスによる診断を可能にしながら、書き込み操作を意図的に厳選し、ガバナンス下に置いています。

ドメイン	ツール	説明
ワークロード	list_pods	ステータスと IP を含む Pod の一覧を取得します
ワークロード	get_pod_logs	コンテナログを取得します
ワークロード	describe_deployment	Deployment の完全な仕様を取得します
ワークロード	list_statefulsets	ロールアウトステータスを含む StatefulSet の一覧を取得します
ワークロード	describe_statefulset	StatefulSet の詳細な仕様／ステータスを取得します
ワークロード	list_daemonsets	スケジューリングステータスを含む DaemonSet の一覧を取得します
ワークロード	describe_daemonset	DaemonSet の詳細な仕様／ステータスを取得します
ワークロード	list_nodes	Ready ステータスを含むクラスターのノードを取得します
デプロイ	scale_deployment	レプリカ数を変更します（デフォルトはドライラン）
デプロイ	restart_pod	Pod を削除して再起動をトリガーします
設定	get_configmap	ConfigMap のデータを読み取ります
設定	describe_namespace_quota	リソースクォータの使用状況を取得します
設定	list_events	Namespace の最近のイベントを取得します
設定	list_persistent_volume_claims	PVC のステータス、バインド済みボリューム、ストレージクラス、容量を取得します
設定	get_effective_permissions	ServiceAccount の SubjectAccessReview マトリックスを取得します
汎用読み取り	list_k8s_resources	任意のリソース種別を対象とした汎用一覧取得
汎用読み取り	get_k8s_resource	任意のリソース種別を対象とした汎用取得
監視	get_hpa_status	HPA のメトリクスとスケーリング状況を取得します
監視	list_warning_events	トリアージ用の Warning イベントを取得します
監視	get_node_pressure	ノードのメモリ／ディスク／PID の圧迫状況を取得します
マルチ	list_clusters	登録済みのすべてのクラスターを取得します
マルチ	get_cluster_info	ノード数、バージョン、アーキテクチャを取得します

拡充が続く全ツール一覧については、docs/developer-guide.md を参照してください。

---

リスク管理

Kubernetes MCP における最大の機能上のリスクは、厳選されていないリソース（StatefulSet、DaemonSet、PVC、CRD など）の可視性が行き止まりになることです。K8sCortex は、次の要素を組み合わせてこの問題に対処します。

• ガバナンス下の書き込み：影響の大きい操作は明示的に行い、ロールによる制限を設け、多くの場合はデフォルトでドライランにします。
• 柔軟な読み取り：汎用読み取りツールで任意のリソース種別を対象とし、診断を可能にします。

これにより、強固なガバナンス体制を維持しながら、実用的なトラブルシューティングの範囲を確保できます。

---

スコープの境界（v1）

K8sCortex は、ガバナンス下にあるプラットフォームインターフェースとして設計されており、制限のない Kubernetes スーパー・クライアントではありません。

• あらゆるリソースに対する汎用書き込み：v1 では意図的にスコープ外としています。書き込み操作は設計上、厳選され、ロールによる制限が設けられています。
• Pod の対話型 exec セッション：v1 では意図的にスコープ外としています。より強力なセッション制御とコマンド単位の監査が必要となるため、後続バージョンでの実装を予定しています。

---

アーキテクチャ

Claude / IDE agents / CI-CD
        │
        ▼
┌──────────────────────────────┐
│     K8sCortex MCP Server     │
│  OIDC → RBAC → Policy → Tool │
│            → Audit           │
│         │                    │
│     Cluster Registry         │
│ kubeconfig│EKS│GKE│KeyVault  │
└──────────┬───────────────────┘
           │
    ┌──────┼──────┬──────┐
    ▼      ▼      ▼      ▼
   AKS    EKS    GKE  OpenShift / local

---

セキュリティ

• 認証：OIDC トークン（発行者、オーディエンス、署名）をリクエストごとに検証します。セッションは作成したユーザーに紐付けられます
• 認可：ロールベースのツールアクセス（developer → platform-engineer）を、クラスターごとのポリシーでさらに制限します
• 監査：呼び出しごとに、ユーザー、ツール、クラスター、プロバイダー、結果を含む JSON 構造化ログを記録します。シークレット値はマスキングされます
• ネットワーク：ClusterIP のみ — パブリックエンドポイントはありません
• 認証情報：有効期限の短い EKS/GKE トークン、または Key Vault の kubeconfig を使用し、有効期限までのみキャッシュします

---

プロジェクト構成

src/
├── index.ts              # HTTP server (StreamableHTTP + SSE)
├── stdio.ts              # Stdio entry point (Claude Desktop)
├── server.ts             # Tool registry, authorization and dispatch
├── auth.ts               # OIDC middleware
├── roles.ts              # RBAC role hierarchy and per-cluster policies
├── audit.ts              # Audit logger with redaction
├── context.ts            # AsyncLocalStorage user context
├── cluster-store.ts      # Per-cluster K8s client cache
├── clusters/
│   ├── registry.ts       # Cluster registry and CLUSTERS_CONFIG loader
│   ├── kubeconfig.ts     # kubeconfig contexts provider
│   ├── eks.ts            # Amazon EKS provider
│   ├── gke.ts            # Google GKE provider
│   └── azure-keyvault.ts # Azure Key Vault provider
└── tools/                # 75 tools in 14 modules: workload, deployment, configuration,
                          # config_management, workload_creation, jobs, network, observability,
                          # resource_intelligence, cloud_awareness, cluster_admin, gitops,
                          # generic_read, multicluster

tests/
├── *.test.ts             # Unit and auth/audit integration tests (vitest)
└── e2e/
    ├── kwok/             # 164-scenario matrix on two simulated clusters (runs in CI)
    └── gke/              # Every tool, both GKE providers and policies on a real GKE cluster

charts/k8scortex/         # Helm chart for the shared HTTP service (tested on kind in CI)
kubernetes/               # The chart rendered to plain manifests, with example values
Dockerfile                # Image published to ghcr.io/apatilgtn/k8scortex-mcp

docs/
├── developer-guide.md    # End-user documentation
├── operator-runbook.md   # Platform team operations
└── slos.md               # Service level objectives

---

テスト

すべてのプッシュで、lint、型チェック、単体テスト、認証／監査の統合テスト、および 2 つの KWOK クラスター（GKE に近い環境と EKS に近い環境）での 164 シナリオのエンドツーエンドテストマトリックスを実行します。リリースは、実際の GKE クラスターに対して npm run test:e2e:gke でも検証されます。v1.1.1 は GKE 1.36 で 100/100 を達成し、このテスト実行で見つかった GKE 固有の 3 件のバグは changelog で修正されています。

---

ドキュメント

• 開発者ガイド — 接続方法、利用可能なツール、クエリの例
• 運用ランブック — デプロイ、アップグレード、認証情報のローテーション、インシデント対応
• SLO — 可用性、レイテンシ、アラートの目標
• 変更履歴

コントリビューション

Issue とプルリクエストを歓迎します。PR を作成する前に npm run release:gate を実行してください。新しいツールには、src/roles.ts のロールと KWOK マトリックスのケースが必要です。

ライセンス

MIT