Kubectl MCP Tool

kubectl-mcp-server

AI との自然言語での会話を通じて、Kubernetes インフラ全体を管理できます。
DevOps の専門家と話すように、クラスターに話しかけましょう。クラッシュした Pod のデバッグ、コストの最適化、アプリケーションのデプロイ、セキュリティ監査、Helm チャートの管理をすべて自然言語で行えます。
CNCF Landscape の一部として、Terraform の隣に掲載

---

インストール

npx でクイックスタート（推奨 — インストール不要）

# Run directly without installation - works instantly!
npx -y kubectl-mcp-server

# Or install globally for faster startup
npm install -g kubectl-mcp-server

または pip でインストール（Python）

pip install kubectl-mcp-server

# Or run it isolated with uv
uvx --from kubectl-mcp-server kubectl-mcp

---

📑 目次

• できること
• kubectl-mcp-server を選ぶ理由
• ライブデモ
• インストール
  • npx ですぐに使い始める
  • pip でインストール
  • Docker
• はじめに
• AI アシスタントで簡単にセットアップ
• 対応するすべての AI アシスタント
• すべての機能
• CLI の使用
• 高度な設定
• ステートレス MCP（2026-07-28）
• エンタープライズ
• セキュリティ
• 連携とエコシステム
• クラスター内デプロイ
• マルチクラスター対応
• アーキテクチャ
• エージェントスキル
• 開発とテスト
• コントリビューション
• サポートとコミュニティ

---

できること

AI アシスタントに自然な言葉で尋ねるだけです。

💬 「Pod がクラッシュする原因は何ですか？」

• ログ、イベント、リソース分析による即時のクラッシュ診断
• 実行可能な推奨事項を伴う根本原因の特定

💬 「レプリカ 3 つで Redis クラスターをデプロイして」

• ベストプラクティスに沿ったデプロイメントを作成
• サービス、永続ストレージ、ヘルスチェックを設定

💬 「リソースを浪費している Pod を教えて」

• AI を活用したコスト最適化分析
• 削減可能なコストを含むリソースの推奨事項

💬 「データベースに接続できないサービスはどれですか？」

• DNS 解決を含むネットワーク接続の診断
• Ingress から Pod までのサービスチェーンを追跡

💬 「すべての名前空間のセキュリティを監査して」

• RBAC 権限の分析
• Secret のセキュリティスキャンと Pod セキュリティポリシー

デフォルトで 26 個、すべてのツールセットで 209 個のツール | 14 個のワークフロープロンプト | 8 個のリソース + 6 個のリソーステンプレート | ステートレス MCP 2026-07-28 | 主要な AI アシスタントすべてに対応

kubectl-mcp-server を選ぶ理由

• 🚀 コンテキストの切り替えをなくす - AI アシスタントとの会話から Kubernetes を直接管理
• 🧠 AI を活用した診断 - 生データだけでなく、インテリジェントなトラブルシューティングを提供
• 💰 コスト最適化機能を内蔵 - 無駄を特定し、実行可能なコスト削減の推奨事項を提示
• 🔒 エンタープライズ対応 - ツールごとのスコープに対応した OAuth 2.1 認証、読み取り専用モード、Secret の編集、フェイルクローズ方式のネットワークバインド
• ⚡ 学習コストゼロ - kubectl コマンドを暗記せず、自然な言葉で操作
• 🌐 幅広い互換性 - Claude、Cursor、Windsurf、Copilot、その他 15 以上の AI ツールに対応
• ☸️ 本番環境向け - ステートレス HTTP によりあらゆるロードバランサーの背後でスケーリング可能、Helm チャート、516 件のテストに合格

クラッシュした Pod のデバッグからクラスターコストの最適化まで、kubectl-mcp-server は AI を活用した DevOps のパートナーです。

ライブデモ

Claude Desktop

Cursor AI

Windsurf

インストール

npx ですぐに使い始める（推奨 - インストール不要）

# Run directly without installation - works instantly!
npx -y kubectl-mcp-server

# Or install globally for faster startup
npm install -g kubectl-mcp-server

または pip でインストール（Python）

pip install kubectl-mcp-server

# Or run it isolated with uv
uvx --from kubectl-mcp-server kubectl-mcp

GitHub リリースからインストール

# Install specific version directly from GitHub release (replace {VERSION} with desired version)
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v{VERSION}/kubectl_mcp_server-{VERSION}-py3-none-any.whl

# Example: Install v2.0.0
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v2.0.0/kubectl_mcp_server-2.0.0-py3-none-any.whl

# Or install latest from git
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git

前提条件

• Python 3.10+ または uv（pip/uvx によるインストールの場合）
• Node.js 18+（npx によるインストールの場合）
• kubectl がインストールされ、設定済みであること
• Kubernetes クラスターへのアクセス

Docker

# Pull from Docker Hub
docker pull rohitghumare64/kubectl-mcp-server:latest

# Or pull from GitHub Container Registry
docker pull ghcr.io/rohitg00/kubectl-mcp-server:latest

# Run with stdio transport (the image runs as UID 10001 with HOME=/home/mcp)
docker run -i --rm -v $HOME/.kube:/home/mcp/.kube:ro rohitghumare64/kubectl-mcp-server:latest

# Run stateless HTTP on localhost only. The container listens on 0.0.0.0, so it refuses
# to start without OAuth (MCP_AUTH_ENABLED) or an explicit MCP_ALLOW_UNAUTHENTICATED=true.
docker run --rm -p 127.0.0.1:8000:8000 -v $HOME/.kube:/home/mcp/.kube:ro \
  -e MCP_ALLOW_UNAUTHENTICATED=true \
  rohitghumare64/kubectl-mcp-server:latest --transport http

はじめに

1. サーバーをテストする（任意）

AI アシスタントと連携する前に、インストールを確認します。

# Check if kubectl is configured
kubectl cluster-info

# Test the MCP server directly
kubectl-mcp-server info

# List all available tools
kubectl-mcp-server tools

# Try calling a tool
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "kube-system"}'

2. AI アシスタントに接続する

お好みの AI アシスタントを選び、設定を追加します。

AI アシスタントで簡単にセットアップ

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

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

Cursor AI

~/.cursor/mcp.json に追加します：

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

Windsurf

~/.config/windsurf/mcp.json に追加します：

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

npx の代わりに Python を使用する

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
      "env": {
        "KUBECONFIG": "/path/to/.kube/config"
      }
    }
  }
}

その他のインテグレーション：GitHub Copilot、Goose、Gemini CLI、Roo Code、その他15 以上のクライアント —> 詳しくは、以下の設定ガイド全文をご覧ください。

3. AI アシスタントを再起動する

設定を追加したら、AI アシスタント （GitHub Copilot、Claude Code、Claude Desktop、Cursor など） を再起動して、MCP サーバーを読み込みます。

4. 次のコマンドを試す

AI アシスタントとの会話を開始し、次のコマンドを試してください：

トラブルシューティング：

"Show me all pods in the kube-system namespace"
"Why is the nginx-deployment pod crashing?"
"Diagnose network connectivity issues in the default namespace"

デプロイ：

"Create a deployment for nginx with 3 replicas"
"Scale my frontend deployment to 5 replicas"
"Roll back the api-server deployment to the previous version"

コストと最適化：

"Which pods are using the most resources?"
"Show me idle resources that are wasting money"
"Analyze cost optimization opportunities in the production namespace"

セキュリティ：

"Audit RBAC permissions in all namespaces"
"Check for insecure secrets and configurations"
"Show me pods running with privileged access"

Helm：

"List all Helm releases in the cluster"
"Install Redis from the Bitnami chart repository"
"Show me the values for my nginx-ingress Helm release"

マルチクラスター：

"List all available Kubernetes contexts"
"Switch to the production cluster context"
"Show me cluster information and version"

MCP クライアントの互換性

すべての MCP 互換 AI アシスタントでシームレスに動作します：

クライアント	ステータス	クライアント	ステータス
Claude Desktop	✅ ネイティブ	Claude Code	✅ ネイティブ
Cursor	✅ ネイティブ	Windsurf	✅ ネイティブ
GitHub Copilot	✅ ネイティブ	OpenAI Codex	✅ ネイティブ
Gemini CLI	✅ ネイティブ	Goose	✅ ネイティブ
Roo Code	✅ ネイティブ	Kilo Code	✅ ネイティブ
Amp	✅ ネイティブ	Trae	✅ ネイティブ
OpenCode	✅ ネイティブ	Kiro CLI	✅ ネイティブ
Antigravity	✅ ネイティブ	Clawdbot	✅ ネイティブ
Droid (Factory)	✅ ネイティブ	任意の MCP クライアント	✅ 互換

サポート対象の AI アシスタント一覧

Claude Code

~/.config/claude-code/mcp.json に追加します：

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

GitHub Copilot (VS Code)

VS Code の settings.json に追加します：

{
  "mcp": {
    "servers": {
      "kubernetes": {
        "command": "npx",
        "args": ["-y", "kubectl-mcp-server"]
      }
    }
  }
}

Goose

~/.config/goose/config.yaml に追加します：

extensions:
  kubernetes:
    command: npx
    args:
      - -y
      - kubectl-mcp-server

Gemini CLI

~/.gemini/settings.json に追加します：

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

Roo Code / Kilo Code

~/.config/roo-code/mcp.json または ~/.config/kilo-code/mcp.json に追加します：

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

機能の全容

ツールセット

ツールの定義はリクエストのたびにコンテキストを消費し、一覧が長くなるほどモデルがツールを選択する精度も低下します。そのため、このサーバーではデフォルトで core および helm ツールセット（26 個のツール）のみを登録します。kubectl_get、kubectl_describe、kubectl_logs、kubectl_apply などはカスタムリソースを含むすべてのリソース種別で動作するため、デフォルトのセットで日常的な作業の大半をカバーできます。それ以外はすべてオプトインです。有効になっているツールセットに含まれないツールは一切登録されないため、呼び出すこともできません。

kubectl-mcp-server                                    # core + helm
kubectl-mcp-server --toolsets default,diagnostics,certs
kubectl-mcp-server --toolsets all                     # all 209 tools
MCP_TOOLSETS=default,gitops kubectl-mcp-server        # same, via environment

detect_ecosystem は、インストールされているオペレーターと、それらをカバーするツールセットを報告します。多くのツールセットを有効にしていて、クライアントがツールを自力で検索できない場合は、--tool-search（MCP_TOOL_SEARCH=true）を追加してください。すると、サーバーはデフォルトのツールに加えて search_tools と call_tool のみを一覧表示し、残りのツールは必要に応じて見つけられます。読み取り専用モード、スコープ、リダクションは、検出されたすべての呼び出しにも適用されます。

特定のエコシステムを深く扱う場合は、オプトインのツールセットよりも、そのプロジェクトが保守している MCP サーバーの方が適していることが一般的です：

エコシステム	MCP サーバー
Argo CD	argoproj-labs/mcp-for-argocd
Flux	Flux Operator MCP サーバー
Kyverno	nirmata/kyverno-mcp
ツールセット	デフォルト
---------	---------
core	はい
helm	はい
helm_dev
ops
diagnostics
security
cost
multicluster
crds
gitops
certs
policy
backup
keda
cilium
rollouts
capi
kubevirt
istio
kind
vind

MCP リソース

参照可能なリソースとして Kubernetes データにアクセスします。

リソース URI	説明
kubeconfig://contexts	利用可能な kubectl コンテキストをすべて一覧表示します
kubeconfig://current-context	現在アクティブなコンテキストを取得します
namespace://current	現在の名前空間を取得します
namespace://list	すべての名前空間を一覧表示します
cluster://info	クラスター情報を取得します
cluster://nodes	ノードの詳細情報を取得します
cluster://version	Kubernetes のバージョンを取得します
cluster://api-resources	利用可能な API リソースを一覧表示します
manifest://deployments/{ns}/{name}	Deployment の YAML を取得します
manifest://services/{ns}/{name}	Service の YAML を取得します
manifest://pods/{ns}/{name}	Pod の YAML を取得します
manifest://configmaps/{ns}/{name}	ConfigMap の YAML を取得します
manifest://secrets/{ns}/{name}	Secret の YAML を取得します（データはマスクされます）
manifest://ingresses/{ns}/{name}	Ingress の YAML を取得します

MCP プロンプト

一般的な Kubernetes 操作向けの、事前構築済みワークフロープロンプトです。

プロンプト	説明
troubleshoot_workload	Pod／Deployment の包括的なトラブルシューティングガイド
deploy_application	ステップごとのデプロイワークフロー
security_audit	セキュリティスキャンと RBAC 分析のワークフロー
cost_optimization	リソース最適化とコスト分析のワークフロー
disaster_recovery	バックアップと復旧計画のワークフロー
debug_networking	Service と接続性のネットワークデバッグ
scale_application	HPA／VPA のベストプラクティスを含むスケーリングガイド
upgrade_cluster	Kubernetes クラスターのアップグレード計画
cluster_health_check	クラスター全体の健全性レビュー
debug_workload	指定したワークロードをステップごとにデバッグします
resource_usage	リソース消費と適正サイジングのレビュー
security_posture	名前空間またはクラスターのセキュリティ態勢レビュー
deployment_checklist	アプリケーションのデプロイ前チェックリスト
incident_response	インシデントの種類別インシデント対応手順書

~/.config/kubectl-mcp/prompts.toml に独自のプロンプトを追加できます。同名のプロンプトは組み込みのものを上書きします。

主な機能

• 🤖 デフォルトツール 26 個、オプトインツール 209 個 - デフォルトでは汎用の kubectl と Helm を使用し、必要に応じてエコシステムのツールセットを利用できます
• 🎯 ワークフロープロンプト 14 個 - 一般的な操作向けの事前構築済みワークフロー
• 📊 リソース 8 個＋テンプレート 6 個 - Kubernetes データを参照可能な形式で公開します
• 🔄 オプトインのエコシステムツールセット - GitOps、cert-manager、policy、Velero、KEDA、Cilium、Rollouts、CAPI、KubeVirt、Istio、kind、vCluster
• ⚡ ステートレス MCP 2026-07-28 - stdio と Streamable HTTP に対応し、古いクライアントは自動的にネゴシエーションされます
• 🔐 セキュリティ優先 - 読み取り専用モード、呼び出しごとの確認、Secret の秘匿化、フラグインジェクション対策
• 🏥 高度な診断 - AI を活用したトラブルシューティングとコスト最適化
• ☸️ マルチクラスター - 各ツールの context パラメーターで任意のクラスターを対象にできます
• 🎡 Helm v3 のフルサポート - チャートのライフサイクルを完全に管理します
• 🔧 強力な CLI - シェルで使いやすいツールの検索と直接呼び出し
• 🐳 クラウドネイティブ - kMCP または kagent を使用してクラスター内にデプロイできます

CLI の使用

組み込み CLI を使うと、AI アシスタントなしでツールを確認してテストできます。

# List all tools with descriptions
kubectl-mcp-server tools -d

# Search for pod-related tools
kubectl-mcp-server grep "*pod*"

# Show specific tool schema
kubectl-mcp-server tools kubectl_get

# Call a tool directly
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "kube-system"}'

# Pipe JSON from stdin
echo '{"resource_type": "pods"}' | kubectl-mcp-server call kubectl_get

# Check dependencies
kubectl-mcp-server doctor

# Show/switch Kubernetes context
kubectl-mcp-server context
kubectl-mcp-server context minikube

# List resources and prompts
kubectl-mcp-server resources
kubectl-mcp-server prompts

# Show server info
kubectl-mcp-server info

CLI の機能

• 構造化されたエラー：実行可能な提案を含むエラーメッセージ
• 色付きの出力：人が読みやすい形式。スクリプト用の JSON モード（--json）にも対応します
• NO_COLOR 対応：NO_COLOR 環境変数を尊重します
• 標準入力に対応：JSON 引数をコマンドにパイプで渡せます

高度な設定

トランスポートモード

# stdio (default) - Claude Desktop, Cursor, Windsurf, Claude Code
kubectl-mcp-server

# Streamable HTTP, stateless, at http://127.0.0.1:8000/mcp
kubectl-mcp-server --transport http --port 8000

# SSE - deprecated by the MCP spec (SEP-2596), session-bound; kept for old clients
kubectl-mcp-server --transport sse --port 8000

サーバーオプション（すべてのフラグで環境変数も読み取ります）：

フラグ	環境変数	デフォルト	説明
--transport	MCP_SERVER_TRANSPORT	stdio	stdio、http / streamable-http、sse
--host	MCP_SERVER_HOST	127.0.0.1	ネットワークトランスポートのバインドアドレス
--port	MCP_SERVER_PORT	8000	ネットワークトランスポートのポート
--allow-unauthenticated	MCP_ALLOW_UNAUTHENTICATED	オフ	OAuth なしでループバック以外のアドレスへのバインドを許可します
--toolsets	MCP_TOOLSETS	default	登録するツールセット（default、all、または名前。ツールセットを参照）
--tool-search	MCP_TOOL_SEARCH	オフ	デフォルトのツールに加えて search_tools／call_tool を一覧表示し、残りのツールは必要に応じて検出します
--read-only	MCP_SAFETY_MODE=read-only	オフ	状態を変更するすべてのツールを非表示にし、ブロックします
--disable-destructive	MCP_SAFETY_MODE=disable-destructive	オフ	作成／更新は許可し、削除はブロックします
--confirm-destructive	MCP_SAFETY_MODE=confirm	オフ	破壊的な呼び出しの前に、ユーザーに確認します
--stateless	MCP_STATELESS_MODE	オフ	Kubernetes API クライアントをキャッシュしません
--watch-kubeconfig	MCP_KUBECONFIG_WATCH	オフ	kubeconfig が変更されたときに再読み込みします
--config			TOML 設定ファイル

環境変数

コア設定：

変数	説明	デフォルト
KUBECONFIG	kubeconfig ファイルのパス	~/.kube/config
MCP_DEBUG	詳細なログ出力を有効にします	false
MCP_LOG_FILE	ログファイルのパス	なし（stdout）

認証（エンタープライズ）：

変数	説明	デフォルト
MCP_AUTH_ENABLED	OAuth 2.1 認証を有効にします	false
MCP_AUTH_ISSUER	OAuth 2.0 認可サーバーの URL	-
MCP_AUTH_JWKS_URI	JWKS エンドポイントの URL	自動導出
MCP_AUTH_AUDIENCE	想定されるトークンのオーディエンス	kubectl-mcp-server
MCP_AUTH_REQUIRED_SCOPES	すべてのトークンに必要なスコープ	mcp:tools
MCP_AUTH_RESOURCE_URL	RFC 9728 メタデータで公開する URL	-

セキュリティとスケーリング：

変数	説明	デフォルト
MCP_SAFETY_MODE	read-only、disable-destructive、confirm、normal（無効な値では起動を停止します）	normal
MCP_MASK_SECRETS	ツールの出力から Secret の値、ベアラートークン、JWT を秘匿します	true
MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS	HTTP の Host／Origin 許可リスト（カンマ区切り）	ループバック
MCP_REQUEST_STATE_KEY	レプリカ間で共有する 32 バイト以上のキー。これにより確認ラウンドを任意のレプリカで処理できます	プロセスごと

エンタープライズ：OAuth 2.1 認証

OAuth 2.1 認証（RFC 9728）で MCP サーバーを保護します。

export MCP_AUTH_ENABLED=true
export MCP_AUTH_ISSUER=https://your-idp.example.com
export MCP_AUTH_AUDIENCE=kubectl-mcp-server
kubectl-mcp-server --transport http --port 8000

対応する ID プロバイダー：Okta、Auth0、Keycloak、Microsoft Entra ID、Google OAuth、および OIDC 準拠のプロバイダー。

スコープ：mcp:tools または mcp:admin を含むトークンは、すべてのツールを呼び出せます。より限定的なトークンを発行するには、MCP_AUTH_REQUIRED_SCOPES=mcp:read を設定します。読み取り専用ツールには mcp:read が必要になり、状態を変更するツールには mcp:write が必要になります。

セキュリティ

• ネットワークへの公開は安全側に失敗します。 HTTP はデフォルトで 127.0.0.1 にバインドされます。それ以外のアドレスにバインドするには、OAuth または --allow-unauthenticated が必要です。Helm チャートは、どちらか一方が指定されていないとレンダリングを拒否します。
• 読み取り専用モードでは書き込みツールが非表示になります。 --read-only（または MCP_SAFETY_MODE=read-only）を指定すると、readOnlyHint が false のすべてのツールが tools/list から除外され、呼び出された場合も拒否されます。
• ステートレスプロトコルでも確認が機能します。 --confirm-destructive は、2026-07-28 対応クライアントに MRTR InputRequiredResult を返し、古いクライアントには elicitation にフォールバックします。承認は特定の操作に厳密に紐付けられます。
• シークレットはマスキングされます。 すべてのツールの結果で、Secret の data、stringData、last-applied-configuration アノテーション、ベアラートークン、JWT は [REDACTED] に置き換えられます。
• フラグのインジェクションは発生しません。 - で始まる識別子の引数（name、namespace、chart、context、ラベルキーなど）は CLI の実行前に拒否されるため、name="--server=https://attacker" が kubectl や helm に渡されることはありません。kubectl_generic は読み取り動詞のみを実行し、認証情報、接続、生の出力に関するフラグをブロックします。
• シェルは使用しません。 すべてのサブプロセス呼び出しで引数リストを使用し、sh -c 経由で実行されるものはありません。kubectl-mcp-tool <= 1.1.1 のシェルインジェクションである CVE-2025-69902 は 1.2.0 で修正されています。それ以前のバージョンを使用している場合はアップグレードしてください。

脆弱性は非公開で報告してください。詳細は SECURITY.md を参照してください。

ステートレス MCP（2026-07-28）

このサーバーは 2026-07-28 仕様に対応しています。initialize ハンドシェイクも Mcp-Session-Id も不要で、機能の確認には server/discover を使用し、リクエストごとに _meta を指定します。2025 年版のクライアントも、stdio と HTTP の両方で、同じプロセスから自動的にネゴシエーションされます。

リクエストが先行するリクエストに依存しないため、HTTP レプリカはスティッキーセッションや共有ストアを使わず、ラウンドロビンロードバランサーの背後でスケールできます。--confirm-destructive を使用する場合は、すべてのレプリカで MCP_REQUEST_STATE_KEY に同じ値を設定してください。

curl -s http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: server/discover' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

インテグレーションとエコシステム

Docker MCP Toolkit

Docker MCP Toolkit と連携できます。

docker mcp server add kubectl-mcp-server mcp/kubectl-mcp-server:latest
docker mcp server configure kubectl-mcp-server --volume "$HOME/.kube:/home/mcp/.kube:ro"
docker mcp server enable kubectl-mcp-server
docker mcp client connect claude

agentregistry

一元管理された agentregistry からインストールできます。

# Install arctl CLI
curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/install.sh | bash

# Install kubectl-mcp-server
arctl mcp install io.github.rohitg00/kubectl-mcp-server

利用方法：PyPI（uvx）、npm（npx）、OCI（docker.io/rohitghumare64/kubectl-mcp-server）

agentgateway

agentgateway を通じて複数の MCP サーバーにルーティングします。

# Start stateless Streamable HTTP
kubectl-mcp-server --transport http --port 8000

# Configure gateway
cat > gateway.yaml <<EOF
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: kubectl-mcp-server
            mcp:
              host: http://localhost:8000/mcp
EOF

# Start gateway
agentgateway --config gateway.yaml

クライアントを http://localhost:3000/mcp に接続してください。

クラスター内デプロイ

オプション 1：kMCP（推奨）

MCP サーバー向けのコントロールプレーンである kMCP を使ってデプロイします。

# Install kMCP
curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash
kmcp install

# Deploy kubectl-mcp-server (easiest)
kmcp deploy package --deployment-name kubectl-mcp-server \
   --manager npx --args kubectl-mcp-server

# Or with Docker image
kmcp deploy --file deploy/kmcp/kmcp.yaml --image rohitghumare64/kubectl-mcp-server:latest

詳細は kMCP クイックスタートを参照してください。

オプション 2：標準 Kubernetes

kubectl/kustomize を使ってデプロイします。

# Using kustomize (recommended)
kubectl apply -k deploy/kubernetes/

# Or individual manifests
kubectl apply -f deploy/kubernetes/namespace.yaml
kubectl apply -f deploy/kubernetes/rbac.yaml
kubectl apply -f deploy/kubernetes/deployment.yaml
kubectl apply -f deploy/kubernetes/service.yaml

# Access via port-forward
kubectl port-forward -n kubectl-mcp svc/kubectl-mcp-server 8000:8000

すべてのマニフェストと設定オプションについては、deploy/ ディレクトリを参照してください。

オプション 3：kagent（AI エージェントフレームワーク）

CNCF の Kubernetes ネイティブ AI エージェントフレームワークである kagent と統合します。

# Install kagent
brew install kagent
kagent install --profile demo

# Register as ToolServer
kubectl apply -f deploy/kagent/toolserver-stdio.yaml

# Open dashboard
kagent dashboard

AI エージェントは、サーバーで有効になっているツールセットを使用できるようになります。kagent クイックスタートを参照してください。

アーキテクチャ

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   AI Assistant  │────▶│   MCP Server     │────▶│  Kubernetes API │
│ (Claude/Cursor) │◀────│ (kubectl-mcp)    │◀────│    (kubectl)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘

MCP サーバーは Model Context Protocol を実装し、自然言語のリクエストを kubectl 操作に変換します。

モジュール構成

kubectl_mcp_tool/
├── mcp_server.py          # Main server (FastMCP, transports)
├── middleware.py          # Safety mode, flag-injection guard, scopes, redaction, metrics
├── toolsets.py            # Toolset registry, server instructions
├── tools/                  # MCP tools, grouped into toolsets
│   ├── kubectl.py         # Generic get/logs/top/scale for every kind, detect_ecosystem
│   ├── pods.py            # Pod exec & diagnostics
│   ├── cluster.py         # Context/cluster management
│   ├── networking.py      # Network and DNS diagnostics
│   ├── security.py        # RBAC, pod security, secret hygiene audits
│   ├── helm.py            # Complete Helm v3 operations
│   ├── operations.py      # kubectl apply/patch/describe/etc
│   ├── diagnostics.py     # Metrics, namespace comparison
│   ├── cost.py            # Resource optimization & cost analysis
│   ├── gitops.py          # GitOps (Flux/ArgoCD)
│   ├── certs.py           # Cert-Manager
│   ├── policy.py          # Policy (Kyverno/Gatekeeper)
│   ├── backup.py          # Backup (Velero)
│   ├── keda.py            # KEDA autoscaling
│   ├── cilium.py          # Cilium/Hubble network observability
│   ├── rollouts.py        # Argo Rollouts/Flagger
│   ├── capi.py            # Cluster API
│   ├── kubevirt.py        # KubeVirt VMs
│   ├── kiali.py           # Istio/Kiali service mesh
│   ├── vind.py            # vCluster (virtual clusters)
│   ├── kind.py            # kind local clusters
│   └── custom_resources.py # CRD discovery
├── resources/              # 8 MCP Resources for data exposure
├── prompts/                # 14 MCP Prompts for workflows
└── cli/                    # CLI interface

エージェントスキル（AI コーディングエージェント向けの 25 個のスキル）

kubernetes-skills/ のスキルを使って、AI コーディングエージェントに Kubernetes の専門知識を追加できます。スキルはエージェントが必要に応じて読み込む専門知識とワークフローを提供し、それぞれ必要なツールセットを明記しています。

クイックインストール

# Any agent (Claude Code, Codex, Cursor, OpenCode, Gemini CLI, ...) via the skills CLI
npx skills add rohitg00/kubectl-mcp-server

# A single skill for a single agent
npx skills add rohitg00/kubectl-mcp-server --skill k8s-helm --agent claude-code

# OpenClaw, from ClawHub (synced from this repo on every merge)
openclaw skills install @rohitg00/k8s-helm

# Or copy into Claude Code directly
cp -r kubernetes-skills/claude/* ~/.claude/skills/

ClawHub で閲覧するか、npx skills add rohitg00/kubectl-mcp-server --list で一覧表示できます。

利用可能なスキル（25）

カテゴリ	スキル
コアリソース	k8s-core, k8s-networking, k8s-storage
ワークロード	k8s-deploy, k8s-operations, k8s-helm
可観測性	k8s-diagnostics, k8s-troubleshoot, k8s-incident
セキュリティ	k8s-security, k8s-policy, k8s-certs
GitOps	k8s-gitops, k8s-rollouts
スケーリング	k8s-autoscaling, k8s-cost, k8s-backup
マルチクラスター	k8s-multicluster, k8s-capi, k8s-kubevirt
開発	k8s-vind, k8s-kind
ネットワーキング	k8s-service-mesh, k8s-cilium
ツール	k8s-cli

他のエージェント形式に変換する

SkillKit を使って、スキルを好みの AI エージェント形式に変換できます。

npm install -g skillkit

# Convert to Cursor format
skillkit translate kubernetes-skills/claude --to cursor --output .cursor/rules/

# Convert to Codex format
skillkit translate kubernetes-skills/claude --to codex --output ./

対応エージェント： Claude、Cursor、Codex、Gemini CLI、GitHub Copilot、Goose、Windsurf、Roo、Amp など。

詳細は kubernetes-skills/README.md をご覧ください。

マルチクラスターのサポート

自然言語を使って、複数の Kubernetes クラスターをシームレスに管理できます。すべてのツールは、省略可能な context パラメーターに対応しており、コンテキストを切り替えることなく任意のクラスターを対象にできます。

Context パラメーター（v1.15.0）

kubectl ベースのツールの多くは、省略可能な context パラメーターを受け付け、特定のクラスターを対象にできます。 注：vCluster（vind）および kind のツールはローカル CLI 経由で実行されるため、context パラメーターを受け付けません。

AI アシスタントに話しかける：

"List pods in the production cluster"
"Get deployments from staging context"
"Show logs from the api-pod in the dev cluster"
"Compare namespaces between production and staging clusters"

context を指定したツールの直接呼び出し：

# Target a specific cluster context
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "default", "context": "production"}'

# Get deployments from staging
kubectl-mcp-server call kubectl_get '{"resource_type": "deployments", "namespace": "app", "context": "staging"}'

# Install Helm chart to production cluster
kubectl-mcp-server call install_helm_chart '{"name": "redis", "chart": "bitnami/redis", "namespace": "cache", "context": "production"}'

# Compare resources across clusters
kubectl-mcp-server call compare_namespaces '{"namespace1": "prod-ns", "namespace2": "staging-ns", "context": "production"}'

コンテキスト管理

AI アシスタントに話しかける：

"List all available Kubernetes contexts"
"Switch to the production cluster"
"Show me details about the staging context"
"What's the current cluster I'm connected to?"

または CLI を直接使用する：

kubectl-mcp-server context                    # Show current context
kubectl-mcp-server context production         # Switch context
kubectl-mcp-server call list_contexts         # List all contexts via MCP

仕組み

• context を省略すると、ツールは現在の kubectl コンテキストを使用します
• context を指定すると、ツールはそのクラスターを直接対象にします
• 分かりやすいように、レスポンスには "context": "production" または "context": "current" が含まれます
• すべての kubeconfig 構成で動作し、KUBECONFIG 環境変数に従います
• クラスター間の操作でコンテキストを切り替える必要はありません

開発とテスト

開発環境のセットアップ

# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

テストの実行

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_tools.py -v

# Run with coverage
pytest tests/ --cov=kubectl_mcp_tool --cov-report=html

# Run only unit tests
pytest tests/ -v -m unit

テスト構成

tests/
├── __init__.py          # Test package
├── conftest.py          # Shared fixtures and mocks
├── test_tools.py        # Unit tests for all MCP tools
├── test_stateless_security.py # Both protocol eras, confirmation, redaction, injection guard
├── test_resources.py    # Tests for 8 MCP Resources
├── test_prompts.py      # Tests for 8 MCP Prompts
└── test_server.py       # Server initialization tests

555 件のテストで網羅する内容： ツールの登録、リソースの公開、プロンプトの生成、2 世代の MCP プロトコルのエンドツーエンドテスト、安全モード、確認ラウンド、Secret の秘匿化、フラグインジェクション、ネットワーク公開、CLI コマンド、エコシステムツール。

コード品質

# Format code
black kubectl_mcp_tool tests

# Sort imports
isort kubectl_mcp_tool tests

# Lint
flake8 kubectl_mcp_tool tests

# Type checking
mypy kubectl_mcp_tool

コントリビューション

コントリビューションを歓迎します ❤️！バグ報告、機能リクエスト、ドキュメントの改善、コードの提供など、どのような貢献も歓迎します。

貢献方法：

• 🐛 GitHub Issues でバグを報告する
• 💡 機能や改善を提案する
• 📝 ドキュメントを改善する
• 🔧 プルリクエストを送信する
• ⭐ 役に立った場合は、プロジェクトにスターを付ける！

開発環境のセットアップ： 上記の「開発とテスト」セクションをご覧ください。

PR を送信する前に：

1. テストを実行する：pytest tests/ -v
2. コードをフォーマットする：black kubectl_mcp_tool tests
3. リントを確認する：flake8 kubectl_mcp_tool tests

サポートとコミュニティ

• 📖 ドキュメント
• 💬 GitHub Discussions
• 🐛 課題トラッカー
• 🎯 機能リクエスト
• 🌟 agentregistry プロフィール

ライセンス

MIT ライセンスです。詳細は LICENSE をご覧ください。

リンクとリソース

パッケージリポジトリ：

• 🐍 PyPI パッケージ
• 📦 npm パッケージ
• 🐳 Docker Hub

プロジェクト：

• 🔧 GitHub リポジトリ
• 🐛 イシュートラッカー
• 📋 変更履歴

エコシステム：

• 📚 Model Context Protocol
• ☸️ Kubernetes ドキュメント

---

Kubernetes と AI のコミュニティのために ❤️ を込めて作られました

kubectl-mcp-server が DevOps をより簡単にしてくれたら、GitHub で ⭐ を付けてください！