KubeAid MCP

KubeAid が管理する Kubernetes クラスター向けの MCP サーバーです。 Claude Code、Claude Desktop、Cursor、その他の MCP 互換クライアントに接続して、 「どのアプリが同期ずれしている？」、「kube-prometheus がなぜ degraded なのか？」、 「cert-manager アプリを同期して」 といった質問ができます。モデルはこのサーバーのツールを呼び出して回答し、 ツールはあなた自身の kubeconfig 認証情報を通じてクラスターにアクセスします。

公式の @modelcontextprotocol/sdk と @kubernetes/client-node を TypeScript で構築しています。

著者: Deep Poharkar

なぜ KubeAid 専用なのか？

KubeAid は GitOps 方式でクラスターを運用します。すべてのアプリケーションは、kubeaid-config リポジトリから生成された ArgoCD の Application であり、自動同期はデフォルトで無効です。Git とクラスターの間のドリフトは正常であり、意図的な同期を待つことになります。汎用の Kubernetes アシスタントはそのワークフローを理解しません。このサーバーはそれを理解します:

• ArgoCD の Application CR は第一級市民です。同期ステータス、健全性、失敗条件、ドリフトしたリソースは、1 回のツール呼び出しで取得できます。

• 同期は、KubeAid における明示的な「今すぐデプロイ」という判断としてモデル化されています。オプトインのフラグでゲートされ、dry_run をサポートし、保護対象としてマークしたコンテキストでは決して許可されません。

• バンドルされたプロンプトは KubeAid の運用習慣をエンコードしています。同期前にドリフトを確認し、クラスターを手編集するのではなく kubeaid-config リポジトリで修正する、といった習慣です。

ツール

読み取りツール — 常に登録されます:

書き込みツール — KUBEAID_MCP_ALLOW_WRITES=true の場合のみ登録されます:

すべてのツールはオプションの context 引数を受け取り、単一のサーバープロセスから kubeconfig 内の任意のクラスターを対象にできます。

プロンプト

プロンプトはクライアントのスラッシュコマンド / メニュー項目として表示され、上記のツールを使用してモデルをワークフローに導きます:

クイックスタート

Node.js 20+ が必要です。

git clone <your-repo-url> kubeaid-mcp
cd kubeaid-mcp
npm install
npm run build

Claude Code

claude mcp add kubeaid -- node "$(pwd)/dist/index.js"

デフォルトは読み取り専用です。書き込みを有効にしつつ本番環境を触れないようにするには:

claude mcp add kubeaid \
  -e KUBEAID_MCP_ALLOW_WRITES=true \
  -e KUBEAID_MCP_PROTECTED_CONTEXTS=prod-cluster-1,prod-cluster-2 \
  -- node "$(pwd)/dist/index.js"

Claude Desktop

設定 → 開発者 → ローカル MCP サーバー を有効にし、そのページで開く設定ファイルに追加します:

{
  "mcpServers": {
    "kubeaid": {
      "command": "node",
      "args": ["/absolute/path/to/kubeaid-mcp/dist/index.js"],
      "env": {
        "KUBEAID_MCP_ALLOW_WRITES": "true",
        "KUBEAID_MCP_PROTECTED_CONTEXTS": "prod-cluster-1"
      }
    }
  }
}

その後、アプリを完全に終了して再度開きます。

設定

すべての設定は環境変数で、起動時に一度だけ読み取られます:

安全モデル

独立した 3 つのレイヤー:

1. 機能ゲーティング — 書き込みが無効 (デフォルト) の場合、変更を伴うツールは決して登録されないため、モデルはそれらを認識すらできません。

2. 保護コンテキスト — すべての変更ハンドラーは、対象コンテキストを KUBEAID_MCP_PROTECTED_CONTEXTS と再チェックし、モデルが何を要求しても保護されたコンテキストを拒否します。

3. クライアント確認 — ツールには MCP の readOnlyHint/destructiveHint アノテーションが付いているため、適切なクライアントはリスクのある呼び出しの前に確認を求めます。

サーバーは独自の認証情報を保持しません。kubeconfig の ID が RBAC で既に許可されている操作しか実行できません。

開発

npm run typecheck   # strict TS, no emit
npm run build       # compile to dist/
npm run smoke       # spawn the server, MCP handshake, list tools + prompts
KUBEAID_MCP_ALLOW_WRITES=true npm run smoke   # verify write tools register

スモークテストはクラスターを必要としません。stdio 上で生の JSON-RPC プロトコルを駆動します。

ロードマップ

• check_chart_updates: デプロイされたチャートのバージョンを、上流の KubeAid argocd-helm-charts ディレクトリと比較。

• Sealed-secrets ヘルパー: SealedSecret のステータスを一覧表示し、失敗したアンシールをフラグ。

• Prometheus/Alertmanager ツール: KubeAid が同梱する kube-prometheus スタックから発火中のアラートを表示。

謝辞

• KubeAid by Obmondo — このサーバーが対象とするクラスター管理スタック。

• Argo CD — KubeAid の基盤となる GitOps エンジン。

ライセンス

MIT © 2026 Deep Poharkar