Kubeview Mcp

KubeView MCP

Kubernetes 診断用の読み取り専用 Model Context Protocol サーバーです。数十個のツールを公開する代わりに、エージェントにサンドボックス化された TypeScript ランタイムを提供します。単一の run_code 呼び出しで Kubernetes、Helm、Argo Workflows、Argo CD を照会し、結果を関連付けて、回答だけを返せます。中間ペイロードがモデルのコンテキストウィンドウを通過することはありません。MCP でのコード実行のパターンに基づいています。

背景：Kubernetes クラスターから MCP ツール呼び出しを排除する

仕組み

v2 では、公開ツールは run_code と、承認が必要な kube_pod_exec の2つだけです。それ以外は、MCP の段階的な検出とプログラムによる呼び出しのガイダンスに従い、サンドボックス内で tools.list()、tools.search()、tools.help() を使って検出します。

run_code は、トップレベルの await を使った実行範囲が制限された TypeScript を実行します。1回の呼び出しで、ワークロードの一覧取得、イベントの関連付け、ログの取得、Helm の状態の差分確認を行い、中間ペイロードをモデル経由で送り返すことなく処理できます。

const pods = await tools.kubernetes.list({ namespace: 'payments' });
const unhealthy = pods.items.filter((p) => p.status?.phase !== 'Running');

return Promise.all(
  unhealthy.map(async (pod) => ({
    pod: pod.metadata?.name,
    logs: await tools.kubernetes.logs({
      namespace: 'payments',
      podName: pod.metadata?.name,
      tailLines: 100,
    }),
  })),
);

• 機密性の高い操作の分離 — サンドボックス化されたコードから kube_pod_exec にアクセスすることはできません。トップレベルの exec には MCP elicitation が必要で、引数ダイジェストに紐付けられ、10分後に期限切れとなり、安全側に倒して失敗します。kube_port_forward はトップレベルツールとして公開されず、コードモード内ではデフォルトで拒否されます。tools.disabled() は、どのポリシーによって機能がブロックされたのか、およびその拒否を設定で変更できるかどうかを報告します。
• API 主導の検出 — Argo Workflows と Argo CD は Kubernetes API から検出され、アクティブな kube コンテキストに限定され、60秒間キャッシュされます。利用できないオプションの API によって起動が妨げられることはありません。
• ネイティブな読み取り — リソース、メトリクス、ログ、イベント、ネットワークプローブには Kubernetes API を使用します。Helm リリースはクラスターの Secret または ConfigMap から解析します。ローカルの helm バイナリは代替手段であり、必須ではありません。

クイックスタート

前提条件： Node.js ≥ 22、およびクラスターへのアクセス（KUBECONFIG またはクラスター内サービスアカウント）。

npx -y kubeview-mcp

# Claude Code
claude mcp add kubernetes -- npx kubeview-mcp

{
  "mcpServers": {
    "kubeview": {
      "command": "npx",
      "args": ["-y", "kubeview-mcp"]
    }
  }
}

Cursor では、/kubeview/code-mode によって型付き API がコンテキストに挿入されます。

設定

クラスター

変数	説明	デフォルト
KUBECONFIG	Kubeconfig のパス（複数指定可）。kubectl と同様に複数のファイルがマージされます	~/.kube/config
MCP_KUBE_CONTEXT	デフォルトのコンテキスト（名前またはエイリアス）。デフォルトではアクティブなコンテキストが使用されます	未設定
MCP_KUBE_CONTEXTS	コンテキストの許可リストとエイリアス。例：dev,staging-*,prod=arn:…/prod（詳細）	すべてのコンテキスト
MCP_K8S_SKIP_TLS_VERIFY	Kubernetes API の TLS 検証をスキップします（true/1）	false
MCP_TIMEOUT	デフォルトの操作タイムアウト（ミリ秒）	プラグインのデフォルト
MCP_HIDE_SENSITIVE	機密データをグローバルにマスクします	false
MCP_DISABLE_KUBERNETES_PLUGIN	Kubernetes プラグインを無効にします（true/1）	未設定
MCP_DISABLE_HELM_PLUGIN	Helm プラグインを無効にします（true/1）	未設定

モードと機能

変数	説明	デフォルト
MCP_MODE	code（デフォルト）、all（別名）、または tools	code
MCP_CODE_MODE_DISABLED_TOOLS	コードモードで無効にするツールをカンマ区切りで指定します。空の場合はすべて有効になります	JSON/デフォルト
MCP_ARGO_TOOLS	Argo の上書き設定：auto、on、off	auto
MCP_ARGOCD_TOOLS	Argo CD の上書き設定：auto、on、off	auto
MCP_LOG_LEVEL	error、warn、info、debug	info
KUBE_MCP_FORCE_VM_SANDBOX	スタンドアロンランタイムで node:vm を強制します	未設定

HTTP トランスポート

変数	説明	デフォルト
MCP_TRANSPORT	stdio または http	stdio
MCP_HTTP_HOST / _PORT	HTTP のバインド先（MCP_TRANSPORT=http の場合）	127.0.0.1:3000
MCP_HTTP_PATH	Streamable HTTP エンドポイントのパス	/mcp
MCP_HTTP_JSON_RESPONSE	SSE より JSON を優先（呼び出し途中の通知は破棄されます）	false
MCP_ALLOWED_HOSTS	ホストの許可リスト（0.0.0.0/:: にバインドする場合は必須）	ローカルのデフォルト
MCP_ALLOWED_ORIGINS	HTTP 用のオリジン許可リスト	未設定
MCP_APPROVAL_STATE_SECRET	共有する 32 バイト以上の署名シークレット。HTTP 承認に必須	一時的（stdio）
MCP_APPROVAL_REPLAY_DIR	1 回限りの HTTP 承認に使用する絶対パスの共有ボリュームディレクトリ	未設定

mkdir -p /tmp/kubeview-mcp-approvals
MCP_APPROVAL_STATE_SECRET='replace-with-at-least-32-random-bytes' \
MCP_APPROVAL_REPLAY_DIR=/tmp/kubeview-mcp-approvals \
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 npx -y kubeview-mcp

エンドポイント：http://127.0.0.1:3000/mcp。HTTP は MCP 2026-07-28 stateless core に準拠しています。リクエストごとに新しいサーバーが起動し、initialize と Mcp-Session-Id は使用しません。各リクエストの _meta には、プロトコルバージョン、クライアント ID、ケイパビリティが含まれます。最新のリクエストでは、ゲートウェイのルーティング用に Mcp-Method/Mcp-Name が追加されます。2025 年当時のクライアントは、同じエンドポイントで SDK のステートレスフォールバックを使用します。呼び出し間で維持する必要がある状態は、ツールの引数またはハンドルとして渡す必要があります。

HTTP モードは、両方の承認用変数が設定されていないと起動しません。複数レプリカのデプロイでは、同じシークレットと書き込み可能な共有リプレイディレクトリが必要です。/tmp の例は単一プロセス専用です。公開されている MCP レジストリエントリーは、引き続き stdio を対象としています。

ツールの種類

MCP_MODE	公開されるツール
未設定 / code / all	run_code、kube_pod_exec
tools	kube_list、kube_get、kube_logs、kube_contexts、helm、kube_pod_exec、および検出された argo と argocd

ドメインツールでは、operation によって処理を指定します。

• helm — list | get | debug
• argo — list | get | logs | cron_list（Workflow または CronWorkflow が検出可能な場合）
• argocd — list | get | resources | logs | history | status（Application が検出可能な場合、または ARGOCD_SERVER と ARGOCD_AUTH_TOKEN が設定されている場合）

検出結果は kube コンテキストごとに 60 秒間キャッシュされます。任意の API が見つからなくても、その API は省略されるだけで、致命的なエラーにはなりません。argo と argocd は、デフォルトコンテキストまたは MCP_KUBE_CONTEXTS に記載された完全一致のコンテキスト名のいずれかで API が存在する場合に登録されます。

複数のクラスター

すべてのクラスター用ツールは、任意の context 引数（kubeconfig のコンテキスト名、または MCP_KUBE_CONTEXTS のエイリアス）を受け取ります。kube_contexts では、対象にできるコンテキストを一覧表示できます。指定しない場合、呼び出しは従来どおり、まず MCP_KUBE_CONTEXT、次に kubeconfig の current-context を使用します。コンテキストはセッション単位ではなく呼び出し単位で指定するため、HTTP モードのステートレス性が保たれ、1 つのスクリプトから複数のクラスターに並行して問い合わせられます。

MCP_KUBE_CONTEXTS はカンマ区切りのリストです。通常のエントリーは、任意の * ワイルドカードを含むコンテキスト名です。alias=context 形式のエントリーは、短い名前を実際のコンテキストに対応付けます。設定すると、一致するコンテキスト、エイリアスの参照先、および MCP_KUBE_CONTEXT のみが利用可能になります。Helm／Argo／Argo CD CLI のフォールバックも対象となり、解決されたコンテキストが --kube-context／--context として渡されます。エイリアスを定義しながらすべてのコンテキストを利用可能にするには、* を追加してください。

MCP_KUBE_CONTEXT=dev \
MCP_KUBE_CONTEXTS='dev,staging-*,prod=arn:aws:eks:eu-west-1:123456789012:cluster/prod' \
npx -y kubeview-mcp

run_code では、context 引数を使ってスクリプト全体のデフォルトを設定するか、tools.withContext() を使って適用範囲を限定します。呼び出しごとの context は常に優先されます。

const staging = tools.withContext('staging-eu');
const [stagingApi, prodApi] = await Promise.all([
  staging.kubernetes.diagnose({ resourceType: 'deployment', name: 'api', namespace: 'shop' }),
  tools.kubernetes.diagnose({ resourceType: 'deployment', name: 'api', namespace: 'shop', context: 'prod' }),
]);
return { staging: stagingApi.summary, prod: prodApi.summary };

kube_pod_exec は承認を求める前にコンテキストを解決します。承認プロンプトにはそのコンテキストが示され、承認はそのコンテキストに紐付けられます。

コードモード

コードモードがデフォルトです（MCP_MODE=code）。エージェントは数十個の MCP ツールを呼び出す代わりに、型付けされたグローバルの tools を使って短い TypeScript を記述します。

run_code 内では、次の機能を利用できます。

• Kubernetes、Helm、および検出された Argo の機能を対象とする、型付けされた tools 名前空間。ライブスキーマから生成されるため、パラメーターが捏造されることはありません。
• 段階的な探索：tools.list()、tools.search()、tools.help()、tools.disabled()（最後のものは、機能がブロックされた理由を報告します）。
• マルチクラスターアクセス：tools.kubernetes.contexts()、tools.withContext(name)、および呼び出しごとの context 引数（複数のクラスターを参照）。
• console と tools のみがスコープ内にある、ロックダウンされたランタイム。ファイルシステム、ネットワーク、process は利用できません。

機能	run_code 内	トップレベルツール
kube_pod_exec	利用できません	呼び出しごとにユーザー承認が必要（10 分間有効、引数に紐付け）
kube_port_forward	デフォルトで拒否（設定可能）	公開されません
その他すべて	利用可能	MCP_MODE=tools の場合のみ

Pod の exec 承認には MCP elicitation を使用し、失敗時は閉じる設計です。スタンドアロンの npm run code-mode ランチャーには信頼できる承認 UI がないため、Pod の exec は常に拒否されます。

ワークロードの診断

コードモードの 1 回の呼び出しで、Pod、Deployment、StatefulSet、DaemonSet、ReplicaSet、Job、CronJob を診断します。

return await tools.kubernetes.diagnose({
  resourceType: 'deployment',
  name: 'payments-api',
  namespace: 'payments',
  includeLogs: true,
});

リソースタイプのデフォルトは pod で、大文字と小文字を区別せず、単数形または複数形を指定できます。Namespace のデフォルトは、現在のコンテキスト、次に default です。診断では UID によってコントローラーの所有関係をたどり、ステータス、イベント、必須設定キー、イメージプル用 Secret、PVC、失敗したコンテナーのログを関連付けます。設定値と Secret の値は返されません。ログとイベントのテキストには MCP_HIDE_SENSITIVE が適用されます。

CLI から Pod を診断するには、次のようにします。

npm run command -- kube_diagnose --name monitor-eks-aid-847484f765-4hwzz

コントローラーの場合は、--resourceType deployment（またはサポートされている別のタイプ）を追加します。ワークロードが現在の Namespace の外にある場合は、--namespace を追加します。

結果には target、context、observedAt、health、summary、findings、evidence、coverage が含まれます。各所見は証拠を参照し、過去の失敗と現在の問題を区別します。考えられる原因は、確認された事実と別に示されます。任意の設定が欠落していても問題ではありません。禁止された読み取り、利用できない読み取り、または必須の読み取りの欠落は coverage.errors に示され、切り詰めやスキップされた読み取りは coverage.truncations に表示されます。ヘルスは healthy、degraded、unknown のいずれかです。収集が不完全でも、確認された失敗は報告される場合があります。

拒否のカスタマイズ

MCP_CODE_MODE_DISABLED_TOOLS（カンマ区切り）で、run_code 内でブロックする機能を指定します。適用順序は次のとおりです。

1. MCP_CODE_MODE_DISABLED_TOOLS 環境変数
2. kube-mcp.code-mode.json の disabledTools
3. デフォルト：["kube_port_forward"]

環境変数の値を空にすると、リストがクリアされます。kube_pod_exec は追加できません。常にブロックされています。

プロトコル

MCP 2026-07-28：

• サーバー側で検証される、入出力契約の JSON Schema 2020-12
• テキストによるフォールバックを備えた、機械可読な structuredContent
• 正確な read-only、destructive、idempotent、open-world アノテーション
• 固定サーフェスとディスカバリー依存サーフェスを示すキャッシュヒントを備えた、決定論的なツール順序
• ディスカバリーとヘッダーベースのルーティング（Mcp-Method、Mcp-Name）を備えたステートレス HTTP
• 実行失敗はツールエラーとして返し、プロトコルエラーは不正なリクエストに限定

ローカル開発

git clone https://github.com/mikhae1/kubeview-mcp.git
cd kubeview-mcp && npm install

npm run build      # compile
npm start          # build + run
npm test           # jest suite
npm run typecheck  # tsc --noEmit

# Invoke a tool directly
npm run command -- kube_list --namespace=default

プロトコルテストでは、SDK v2 クライアントを 2026-07-28 に固定し、サーバーハンドラーをプロセス内で経由してルーティングします（ポートを開放しません）。

npm test -- --runInBand \
  tests/server/StreamableHttpTransport.integration.test.ts \
  tests/server/StreamableHttpRuntime.test.ts \
  tests/server/TransportConfig.test.ts \
  tests/compat/McpSdkCompatibility.test.ts

コントリビューション

コントリビューションを歓迎します！お気軽にイシューまたはプルリクエストを送信してください。

ライセンス

MIT © mikhae1