KubeStellar MCP

kubestellar-mcp

Claude Code 向けの AI 搭載マルチクラスター Kubernetes ツールです。

マルチクラスターの現実に、シングルクラスターの UX を — クラスターではなく、アプリを中心に作業できます。

KubeStellar を選ぶ理由

kubestellar-mcp は、マルチクラスター Kubernetes オーケストレーションの CNCF Sandbox エコシステムである KubeStellar プラットフォームへの AI エントリーポイントです。

サブプロジェクト	役割
kubestellar	コアエンジン — BindingPolicy、WDS、ITS、WEC によるワークロード伝播
console	Web ダッシュボード — 300 以上のカード、AI ミッション、GPU および LLM-d のモニタリング
console-marketplace	コミュニティ製カードプリセット 153 種類以上（GPU/AI/ML、ArgoCD、OPA、Falco、セキュリティ）
console-kb	AI ナレッジベース — コミュニティのミッションと運用ランブック
kubestellar-mcp	このリポジトリ — Claude、Cursor、Windsurf、VS Code 向け MCP サーバー

kubestellar-mcp を使うと、AI エージェントが自然言語でクラスターを調査、操作できます。ビジュアルダッシュボードと AI ミッションについては、KubeStellar Console をご覧ください。

コンポーネント

バイナリ	説明
kubestellar-ops	マルチクラスター診断、RBAC 分析、セキュリティチェック
kubestellar-deploy	アプリ中心のデプロイ、GitOps、スマートなワークロード配置

ドキュメント

追加のドキュメントは docs/ にあります。

• docs/index.md - 詳細なセットアップ、プラグインのワークフロー、CLI の使い方、運用ガイダンス
• docs/ARCHITECTURE.md - 2 つの MCP サーバーのアーキテクチャ概要とコントリビューターガイド、リクエストのライフサイクル、新しいツールの追加方法

新しい MCP 機能を追加する場合は、docs/ARCHITECTURE.md から始めてください。サーバーの構成や、新しいツールを追加すべき場所を把握するのに最適なガイドです。

運用

• docs/slo.md - サービスレベル目標と指標
• docs/alerts/ - SLO に対応したインポート可能な Prometheus アラートルール
• docs/dashboards/ - インポート可能な Grafana ダッシュボード
• runbooks/ - 運用ランブック（起動／停止、クラスター検出の失敗、認証情報のローテーション、接続の喪失、リリースのロールバック）
• docs/postmortem-template.md - インシデントの事後分析テンプレート
• docs/severity-levels.md - インシデントテンプレートと事後分析要件で使用する P1～P4 のインシデント重大度基準

インストール

Homebrew（推奨）

brew tap kubestellar/tap

# Install diagnostics tools
brew install kubestellar-ops

# Install deployment tools
brew install kubestellar-deploy

# Or install both
brew install kubestellar-ops kubestellar-deploy

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

GitHub Releases からダウンロードしてください。

ソースからインストール

前提条件： Go 1.26 以降（go version で確認できます）

git clone https://github.com/kubestellar/kubestellar-mcp.git
cd kubestellar-mcp

# Build both binaries
go build -o bin/kubestellar-ops ./cmd/kubestellar-ops
go build -o bin/kubestellar-deploy ./cmd/kubestellar-deploy

sudo mv bin/kubestellar-* /usr/local/bin/

Claude Code プラグイン

手順 1：KubeStellar Marketplace を追加する

Claude Code で、次を実行します。

/plugin marketplace add kubestellar/claude-plugins

手順 2：プラグインをインストールする

/plugin install kubestellar-ops
/plugin install kubestellar-deploy

または：

1. /plugin に移動 → Marketplaces タブ → kubestellar marketplace の Update をクリック
2. /plugin に移動 → Discover タブ → kubestellar-ops および／または kubestellar-deploy をインストール

手順 3：確認する

Claude Code で /mcp を実行すると、次のように表示されます。

plugin:kubestellar-ops:kubestellar-ops · ✓ connected
plugin:kubestellar-deploy:kubestellar-deploy · ✓ connected

プロンプトなしでツールを許可する

~/.claude/settings.json に追加します。

{
  "permissions": {
    "allow": [
      "mcp__plugin_kubestellar-ops_kubestellar-ops__*",
      "mcp__plugin_kubestellar-deploy_kubestellar-deploy__*"
    ]
  }
}

または、Claude Code で次を実行します。

/allowed-tools add mcp__plugin_kubestellar-ops_kubestellar-ops__*
/allowed-tools add mcp__plugin_kubestellar-deploy_kubestellar-deploy__*

その他の AI クライアント（VS Code、Cursor、Windsurf）

どちらのバイナリも、kubestellar-ops --mcp-server または kubestellar-deploy --mcp-server を使って汎用 MCP stdio サーバーとして実行できます。MCP 互換のクライアントであれば、stdio 経由でバイナリを使用できます。

VS Code（GitHub Copilot）

.vscode/mcp.json を作成します。

{
  "servers": {
    "kubestellar-ops": {
      "command": "kubestellar-ops",
      "args": ["--mcp-server"]
    }
  }
}

Cursor

.cursor/mcp.json を作成します。

{
  "mcpServers": {
    "kubestellar-ops": {
      "command": "kubestellar-ops",
      "args": ["--mcp-server"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "kubestellar-ops": {
      "command": "kubestellar-ops",
      "args": ["--mcp-server"]
    }
  }
}

OpenCode

OpenCode はオープンソースの AI コーディングエージェントです。 プロジェクトの opencode.json または opencode.jsonc に以下を追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kubestellar-ops": {
      "type": "local",
      "command": ["kubestellar-ops", "--mcp-server"],
      "enabled": true
    },
    "kubestellar-deploy": {
      "type": "local",
      "command": ["kubestellar-deploy", "--mcp-server"],
      "enabled": true
    }
  }
}

追加後、opencode mcp list を実行し、両方のサーバーが接続済みと表示されることを確認します。

AI エージェント向け — このメッセージをコピーして OpenCode のセッションに貼り付けると、MCP ツールを自動的に設定できます。

kubestellar-ops と kubestellar-deploy をインストールします：

  # macOS — Homebrew
  brew tap kubestellar/tap
  brew install kubestellar-ops kubestellar-deploy

  # Linux — GitHub Releases からダウンロード
  curl -LO https://github.com/kubestellar/kubestellar-mcp/releases/latest/download/kubestellar-ops_linux_amd64.tar.gz
  curl -LO https://github.com/kubestellar/kubestellar-mcp/releases/latest/download/kubestellar-deploy_linux_amd64.tar.gz
  tar xzf kubestellar-ops_linux_amd64.tar.gz
  tar xzf kubestellar-deploy_linux_amd64.tar.gz
  sudo mv kubestellar-ops kubestellar-deploy /usr/local/bin/

  # またはソースからビルド（任意の OS、Go 1.26+ が必要）
  git clone https://github.com/kubestellar/kubestellar-mcp.git
  cd kubestellar-mcp
  go build -o /usr/local/bin/kubestellar-ops ./cmd/kubestellar-ops
  go build -o /usr/local/bin/kubestellar-deploy ./cmd/kubestellar-deploy

次に、プロジェクトのルートに opencode.jsonc を作成します：
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "kubestellar-ops": {
        "type": "local",
        "command": ["kubestellar-ops", "--mcp-server"],
        "enabled": true
      },
      "kubestellar-deploy": {
        "type": "local",
        "command": ["kubestellar-deploy", "--mcp-server"],
        "enabled": true
      }
    }
  }

次のコマンドで確認します：opencode mcp list

汎用 MCP クライアント（stdio）

kubestellar-ops --mcp-server
kubestellar-deploy --mcp-server

Kubernetes RBAC

MCP バイナリはデフォルトでアクティブな kubeconfig を使用します。クラスター内で実行する場合は、同じ権限をポッドの ServiceAccount に割り当ててください。

ユースケース	一般的な権限
kubestellar-ops 読み取り専用	namespaces、nodes、pods、pods/log、services、endpoints、deployments、replica sets、statefulsets、daemonsets、jobs、cronjobs、events、resourcequotas、limitranges、roles、rolebindings、clusterroles、clusterrolebindings に対する get、list、watch
kubestellar-deploy 書き込み	上記のすべてに加え、管理する予定のリソースタイプに対する create、update、patch、delete

読み取り専用 ClusterRole の例：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubestellar-mcp-readonly
rules:
  - apiGroups: [""]
    resources: ["namespaces", "nodes", "pods", "pods/log", "services", "endpoints", "events", "resourcequotas", "limitranges"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps", "batch"]
    resources: ["deployments", "replicasets", "statefulsets", "daemonsets", "jobs", "cronjobs"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["roles", "rolebindings", "clusterroles", "clusterrolebindings"]
    verbs: ["get", "list", "watch"]

書き込みワークフローでは、実際に必要なリソースルールに create、update、patch、delete を追加します。

トラブルシューティング

プラグインが表示されない

• バイナリのインストールまたはアップグレード後に、Claude Code、VS Code、Cursor、または Windsurf を再起動します。
• which kubestellar-ops を実行して、バイナリが PATH 上にあることを確認します。
• 見つからない場合は再インストールするか、すでに PATH に含まれているディレクトリに移動します。

権限／RBAC エラー

• kubectl auth can-i --list を実行して、現在の ID がアクセスできる対象を確認します。
• 出力を上記の Kubernetes RBAC セクションで説明されている権限と比較します。
• 必要に応じて、MCP クライアントを再試行する前に Role、ClusterRole、またはバインディングを更新します。

kubeconfig の問題

• kubectl config current-context を実行して、アクティブなコンテキストを確認します。
• KUBECONFIG が設定され、想定している kubeconfig ファイルを指しているか確認します。
• 間違ったクラスターが選択されている場合は、コンテキストを切り替えるか環境変数を更新してから、再試行します。

手動スモークテスト

• AI クライアントを開かずに、MCP サーバーが起動することを確認できます。
• 以下の initialize リクエストを実行し、JSON-RPC の応答が返ることを確認します。

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | ./bin/kubestellar-ops --mcp-server

更新

Homebrew で CLI ツールを更新します：

brew update
brew upgrade kubestellar-ops kubestellar-deploy

Claude Code のプラグインを更新します：

/plugin update kubestellar-ops
/plugin update kubestellar-deploy

---

kubestellar-ops

マルチクラスター Kubernetes の診断、RBAC 分析、セキュリティチェック。

使用例

• "Kubernetes クラスターを一覧表示して"
• "すべてのクラスターで問題のある Pod を探して"
• "セキュリティの設定ミスがないか確認して"
• "admin サービスアカウントにはどのような権限がありますか？"
• "kube-system の警告イベントを表示して"

機能

カテゴリ	ツール
クラスター	list_clusters, get_cluster_health, get_nodes, audit_kubeconfig
ワークロード	get_pods, get_deployments, get_services, get_events, describe_pod, get_pod_logs
RBAC	get_roles, get_cluster_roles, get_role_bindings, can_i, analyze_subject_permissions
診断	find_pod_issues, find_deployment_issues, check_resource_limits, check_security_issues
Gatekeeper	check_gatekeeper, install_ownership_policy, list_ownership_violations
アップグレード	detect_cluster_type, get_cluster_version_info, check_helm_release_upgrades
GitOps	detect_drift

スラッシュコマンド

コマンド	説明
/k8s-health	すべてのクラスターの健全性を確認
/k8s-issues	Pod とデプロイメントの問題を探す
/k8s-security	セキュリティの設定ミスがないか確認
/k8s-rbac	RBAC 権限を分析
/k8s-analyze	名前空間を包括的に分析
/k8s-audit-kubeconfig	kubeconfig のクラスターを監査し、クリーンアップを推奨
/k8s-ownership	OPA Gatekeeper で所有権の追跡を管理
/k8s-upgrade-check	利用可能なアップグレードを確認
/k8s-upgrade	クラスターをアップグレード（マスターとノード）

---

kubestellar-deploy

アプリ中心のマルチクラスターのデプロイと運用。

使用例

• "nginx はどこで実行されていますか？"
• "api サービスのログを取得して"
• "GPU を搭載したクラスターに ML モデルをデプロイして"
• "クラスターは git と同期していますか？"
• "すべてのクラスターでアプリを 5 レプリカにスケールして"

機能

カテゴリ	ツール
アプリの検出	get_app_instances, get_app_status, get_app_logs
デプロイ	deploy_app, scale_app, patch_app
配置	list_cluster_capabilities, find_clusters_for_workload
GitOps	sync_from_git, detect_drift, reconcile, preview_changes
Helm	helm_install, helm_uninstall, helm_list, helm_rollback
Kustomize	kustomize_build, kustomize_apply, kustomize_delete
リソース	kubectl_apply, delete_resource
ラベル	add_labels, remove_labels

スラッシュコマンド

コマンド	説明
/app-status	すべてのクラスターにおけるアプリのステータスを表示
/app-logs	アプリの集約ログを取得
/deploy	アプリをデプロイまたは更新
/gitops-sync	クラスターを git と同期
/gitops-drift	git との差分を確認

ワークフローの例

「アプリはどこで実行されていますか？」

nginx is running on 3 clusters:
  - prod-east: 3 replicas, healthy
  - prod-west: 3 replicas, healthy
  - staging: 1 replica, healthy

「GPU クラスターにデプロイ」

Found 2 clusters with nvidia.com/gpu
Deployed to gpu-cluster-1, gpu-cluster-2
All healthy

「差分を確認」

Drift detected:
  - prod-west: ConfigMap/app-config differs
  - staging: Deployment/api has extra replicas

「Helm で nginx-ingress をインストール」

Installing nginx-ingress to 3 clusters...
  - prod-east: Installed nginx-ingress v1.10.0
  - prod-west: Installed nginx-ingress v1.10.0
  - staging: Installed nginx-ingress v1.10.0
All releases healthy

「kustomize のオーバーレイを適用」

Building kustomize from overlays/production...
Applied to 2 clusters:
  - prod-east: 5 resources applied
  - prod-west: 5 resources applied

「テスト用デプロイメントを削除」

Deleted deployment/test from 3 clusters:
  - prod-east: deleted
  - prod-west: deleted
  - staging: deleted

---

CLI の使用方法

kubestellar-ops

# Run as MCP server (for Claude Code)
kubestellar-ops --mcp-server

# List clusters
kubestellar-ops clusters list

# Check cluster health
kubestellar-ops clusters health

kubestellar-deploy

# Run as MCP server (deployment, GitOps, Helm, kubectl, and kustomize tools)
kubestellar-deploy --mcp-server

# Show version information
kubestellar-deploy version

# Generate shell completion
kubestellar-deploy completion bash

kubestellar-deploy では、現在、単独で実行できるデプロイ用サブコマンドは提供されていません。MCP サーバーモード以外では、CLI で使用できるのは version、completion、help などの情報表示コマンドのみです。アプリのデプロイ、GitOps、Helm、kubectl、kustomize、ラベル付けのワークフローは、--mcp-server で起動する MCP ツールサーバーから利用できます。別の Kubernetes 環境を対象にするには、バイナリの起動前に、目的の kubeconfig を KUBECONFIG で指定するか、その kubeconfig 内でアクティブなコンテキストを切り替えてください。

環境変数

変数	使用元	説明
KUBECONFIG	kubestellar-ops、kubestellar-deploy	デフォルトの Kubernetes クライアント検索パスの代わりに使用する kubeconfig ファイルのパス
ANTHROPIC_API_KEY	kubestellar-ops	query コマンドおよび Claude を利用した自然言語でのクラスタークエリに必要です

関連する実行時フラグ

kubestellar-ops は kubectl の標準的な Kubernetes クライアントフラグも継承するため、追加の環境変数を使わずに、実行時にクラスターの選択やリクエストの動作を上書きできます。一般的な例を以下に示します。

• kubeconfig コンテキストを選択する --context
• 名前空間を対象とする操作の範囲を指定する --namespace
• API リクエストのタイムアウトを上書きする --request-timeout
• 高度な認証／接続設定を上書きする --cluster、--user、--server、--token、および TLS フラグ
• KubeStellar 固有の動作を指定する --all-clusters、--target-cluster、および --mcp-server

kubestellar-deploy が現在公開している実行時フラグは --mcp-server で、Kubernetes クライアントの設定以外に追加の環境変数は必要ありません。

関連プロジェクト

• KubeStellar - マルチクラスターオーケストレーションプラットフォーム
• KubeStellar Console - マルチクラスター管理のための AI 搭載ウェブダッシュボード

コントリビューション

コントリビューションを歓迎します！コントリビューションガイドラインをお読みください。

ライセンス

Apache License 2.0 - 詳細はLICENSEをご覧ください。