マルチクラスター Kubernetes MCP サーバー
複数の Kubernetes クラスターを同時に管理するための MCP（Model Context Protocol）サーバーです。クラスター操作、リソース管理、モニタリング、RBAC、ストレージ、ネットワーキングなどを網羅する 60 以上のツールを提供し、Claude Desktop などの AI アシスタントから利用できます。
クイックスタート
Smithery 経由でインストール
npx -y @smithery/cli install @razvanmacovei/k8s-multicluster-mcp --client claude
手動インストール
git clone https://github.com/razvanmacovei/k8s-multicluster-mcp.git
cd k8s-multicluster-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 app.py
Docker
docker build -t k8s-mcp .
docker run -v ~/.kube:/root/.kube k8s-mcp
設定
Claude Desktop / MCP クライアント
MCP クライアントの設定に追加します。
{
"mcpServers": {
"kubernetes": {
"command": "python3",
"args": ["/path/to/k8s-multicluster-mcp/app.py"],
"env": {
"KUBECONFIG_DIR": "/path/to/your/kubeconfigs"
}
}
}
}
環境変数
| 変数 | デフォルト | 説明 |
|---|
KUBECONFIG_DIR | ~/.kube | kubeconfig ファイルを含むディレクトリです。各ファイルには 1 つ以上のコンテキストを含めることができます。 |
kubeconfig ファイルを設定したディレクトリに配置します。サーバーは、すべてのファイルに含まれるコンテキストを自動的に検出します。
前提条件
- Python 3.11 以降
- 有効なクラスター認証情報を含む kubeconfig ファイルが 1 つ以上あること
k8s_top_* および k8s_cluster_info ツールを使用するには、クラスターに metrics-server がインストールされていること
マルチクラスター管理
このサーバーは、複数の Kubernetes クラスターを管理するために特化して構築されています。
- 自動検出：
KUBECONFIG_DIR 内のすべての kubeconfig ファイルをスキャンし、コンテキストを集約します
- 名前の部分一致：
arn:aws:eks:us-east-1:123456:cluster/prod-cluster の代わりに prod を使用できます
- クラスター横断操作：クラスター間でリソース、健全性、設定を比較します
- コンテキストキャッシュ：効率的な 30 秒 TTL キャッシュにより、呼び出しごとに kubeconfig ファイルを読み直す必要がありません
- 一元管理：単一のインターフェースから dev、staging、production を管理します
ツールのリファレンス（60 以上のツール）
クラスターとコンテキストの管理（6 ツール）
| ツール | 説明 |
|---|
k8s_get_contexts | すべての kubeconfig ファイルにある利用可能なコンテキストを一覧表示します |
k8s_get_namespaces | クラスター内のすべての名前空間を一覧表示します |
k8s_create_ns | オプションでラベルやアノテーションを指定して、新しい名前空間を作成します |
k8s_delete_ns | 名前空間を削除します（システム名前空間は保護されます） |
k8s_get_nodes | ステータス、ロール、容量、バージョンを含むすべてのノードを一覧表示します |
k8s_cluster_info | クラスターの健全性の概要を包括的に表示します（ノード、ポッド、デプロイ、警告） |
リソースの検出と調査（7 ツール）
| ツール | 説明 |
|---|
k8s_get_resources | 任意の種類のリソース（ポッド、デプロイ、サービス、イングレスなど）を一覧表示します |
k8s_get_resource | 単一のリソースの完全な定義を取得します |
k8s_get_pod_logs | 期間による絞り込みとコンテナー選択に対応したポッドログを取得します |
k8s_get_events | 名前空間内のクラスターイベントを、最新のものから順に一覧表示します |
k8s_describe | kubectl describe に似た、リソースの詳細な説明を表示します |
k8s_apis | クラスターで利用可能なすべての API グループとリソースを一覧表示します |
k8s_crds | バージョンとスコープを含むすべてのカスタムリソース定義を一覧表示します |
メトリクスとモニタリング（3 ツール）
| ツール | 説明 |
|---|
k8s_top_nodes | ノードの CPU／メモリ使用量を容量と合わせて表示します |
k8s_top_pods | ポッド／コンテナーの CPU／メモリ使用量を表示します |
k8s_diagnose_application | 問題の検出と推奨事項を含む、アプリの包括的な診断を行います |
ロールアウト管理（6 ツール）
| ツール | 説明 |
|---|
k8s_rollout_status | デプロイ／ステートフルセット／デーモンセットのロールアウト状況を取得します |
k8s_rollout_history | リビジョン履歴を取得します |
k8s_rollout_undo | 以前のリビジョンにロールバックします |
k8s_rollout_restart | ローリング再起動を開始します |
k8s_rollout_pause | 進行中のロールアウトを一時停止します |
k8s_rollout_resume | 一時停止中のロールアウトを再開します |
スケーリング（3 ツール）
| ツール | 説明 |
|---|
k8s_scale_resource | deployment/statefulset/replicaset を N 個のレプリカにスケーリングします |
k8s_autoscale_resource | Horizontal Pod Autoscaler（HPA）を設定します |
k8s_update_resources | コンテナの CPU／メモリのリクエストと制限を更新します |
リソースの CRUD（6 ツール）
| ツール | 説明 |
|---|
k8s_create_resource | YAML／JSON の内容からリソースを作成します |
k8s_apply_resource | 設定を適用します（kubectl apply のように作成または更新します） |
k8s_delete_resource | 任意のリソースタイプを削除します。強制削除／猶予期間を指定できます |
k8s_patch_resource | ストラテジックマージパッチで特定のフィールドを更新します |
k8s_label_resource | リソースのラベルを追加または更新します |
k8s_annotate_resource | リソースのアノテーションを追加または更新します |
ワークロード管理（3 ツール）
| ツール | 説明 |
|---|
k8s_expose_resource | deployment/pod を新しい Service として公開します |
k8s_run_pod | 指定したイメージで Pod を作成して実行します |
k8s_set_resources_for_container | コンテナのリソース制限／リクエストを設定します |
ノード管理（5 ツール）
| ツール | 説明 |
|---|
k8s_cordon_node | ノードをスケジュール不可としてマークします |
k8s_uncordon_node | ノードをスケジュール可能としてマークします |
k8s_drain_node | Pod を退避させてノードをドレインします（メンテナンス用） |
k8s_taint_node | ノードにテイントを追加します |
k8s_untaint_node | ノードからテイントを削除します |
Pod 操作（1 ツール）
| ツール | 説明 |
|---|
k8s_pod_exec | コンテナ内でコマンドを実行します（引用符で囲んだ引数に対応） |
Secrets と ConfigMaps（6 ツール）
| ツール | 説明 |
|---|
k8s_list_secret | メタデータ付きで Secret を一覧表示します（セキュリティ保護のため値は非表示） |
k8s_get_secret_detail | Secret を取得します。値をデコードするかどうかを指定できます |
k8s_create_secret_resource | 新しい Secret を作成します（値は自動的に Base64 エンコードされます） |
k8s_list_configmap | キー名とともに ConfigMap を一覧表示します |
k8s_get_configmap_detail | 全データの内容を含む ConfigMap を取得します |
k8s_create_configmap_resource | 新しい ConfigMap を作成します |
RBAC（5 ツール）
| ツール | 説明 |
|---|
k8s_get_roles | 権限ルール付きで RBAC Roles を一覧表示します |
k8s_get_clusterroles | RBAC ClusterRoles を一覧表示します |
k8s_get_rolebindings | RoleBindings を一覧表示します（誰がどのロールを持っているか） |
k8s_get_clusterrolebindings | ClusterRoleBindings を一覧表示します |
k8s_get_service_accounts | ServiceAccounts を一覧表示します |
ストレージ（3 ツール）
| ツール | 説明 |
|---|
k8s_get_pvcs | ステータス、容量、ストレージクラスとともに PersistentVolumeClaims を一覧表示します |
k8s_get_pvs | 容量とバインドされたクレームとともに PersistentVolumes を一覧表示します |
k8s_get_storage_classes | プロビジョナーとデフォルトの状態とともに StorageClasses を一覧表示します |
ネットワーキング（1 ツール）
| ツール | 説明 |
|---|
k8s_get_network_policies | Pod セレクターとルール数とともに NetworkPolicies を一覧表示します |
Job 管理（2 ツール）
| ツール | 説明 |
|---|
k8s_get_jobs | 完了ステータスと実行時間とともに Jobs を一覧表示します |
k8s_get_cronjobs | スケジュール、一時停止状態、最終実行とともに CronJobs を一覧表示します |
使用例
クラスターのヘルスチェック
Give me a health overview of my production cluster.
マルチクラスターの比較
Compare the number of pods running in the 'backend' namespace between my 'prod' and 'staging' contexts.
アプリケーションの問題を診断する
My deployment 'my-app' in the 'production' namespace is having issues. Can you diagnose what's wrong?
リソースをスケーリングする
Scale the 'backend' deployment in the 'default' namespace to 5 replicas.
リソース管理
Delete the failed job 'data-migration-v1' in the 'batch' namespace.
Create a new namespace called 'staging' with the label environment=staging.
Secret 管理
List all secrets in the 'production' namespace and show me the keys in the 'api-credentials' secret.
RBAC の調査
Show me all role bindings in the 'default' namespace -- who has access to what?
ストレージの概要
List all PVCs in the cluster and show which ones are Pending.
ノードのメンテナンス
Cordon node 'worker-3', drain it ignoring DaemonSets, then uncordon when maintenance is complete.
Deployment のロールバック
Roll back the 'api-gateway' deployment in the 'services' namespace to the previous version.
Pod 内で実行する
Run 'ls -la /app/config' inside the 'app' container of pod 'web-app-xyz' in the 'default' namespace.
リソースを作成する
Create a new deployment with this YAML:
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
namespace: default
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.27
ports:
- containerPort: 80
アーキテクチャ
k8s-multicluster-mcp/
├── app.py # MCP server entry point & tool registration
├── src/
│ ├── utils/
│ │ ├── k8s_client.py # Multi-cluster client with context caching
│ │ └── pluralize.py # Kubernetes resource kind pluralization
│ └── tools/
│ ├── contexts.py # Context listing
│ ├── namespaces.py # Namespace listing
│ ├── namespace_management.py # Namespace create/delete
│ ├── nodes.py # Node listing
│ ├── pods.py # Resource listing & pod logs
│ ├── resources.py # Single resource retrieval
│ ├── events.py # Event listing
│ ├── describe.py # kubectl describe equivalent
│ ├── api_discovery.py # API & CRD discovery
│ ├── metrics.py # Node/pod metrics (top)
│ ├── diagnosis.py # Application diagnostics
│ ├── cluster_health.py # Cluster health summary
│ ├── rollouts.py # Rollout management
│ ├── scaling.py # Scale & autoscale & resource updates
│ ├── resource_management.py # Create, apply, patch, label, annotate
│ ├── delete_resource.py # Resource deletion
│ ├── workload_management.py # Expose, run pod, set resources
│ ├── node_management.py # Cordon, drain, taint
│ ├── pod_operations.py # Exec into pods
│ ├── secret_configmap.py # Secret & ConfigMap management
│ ├── rbac.py # Roles, bindings, service accounts
│ ├── storage_network.py # PVC, PV, StorageClass, NetworkPolicy
│ └── job_management.py # Jobs & CronJobs
├── requirements.txt
├── pyproject.toml
├── Dockerfile
└── smithery.yaml
v2.0.0 の新機能
- 20 個以上の新しいツール：リソースの削除、ネームスペースの管理、シークレットと ConfigMap、RBAC の調査、ストレージとネットワークの可視化、ジョブの管理、クラスターの健全性の概要、ポッドの作成
- バグ修正：リソースの複数形化を修正（例：
Ingress → ingresses。ingresss ではありません）、引用符で囲まれた引数に対応するためポッドの exec コマンドの分割を修正、タイムアウトパラメーターの処理を修正
- パフォーマンス：コンテキストの検出で、コンテキストからファイルへの直接マッピングを使用する有効期間 30 秒のキャッシュを導入し、冗長なファイルスキャンを排除しました
- ツールの説明を改善：AI アシスタントとの連携を強化するため、60 個以上すべてのツールに詳細な説明を追加しました
- 依存関係を整理：未使用の
fastapi と uvicorn の依存関係を削除しました
- セキュリティ：ネームスペースの削除時にシステムネームスペースを保護し、シークレットの値をデフォルトで非表示にしました
コントリビューション
コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。
