kubectl-mcp

AIエージェントがKubernetesクラスターを平易な英語で調査できるようにするMCP（Model Context Protocol）サーバーです。「過去1時間に再起動したポッドはどれ？」 と尋ねると、実際の回答が得られます。

Teresa Tran によって構築されました。

なぜ

LLMアシスタントはkubectlコマンドの説明は得意ですが、実際に安全に実行するのは苦手です。kubectl-mcpは、読み取り専用のクラスター調査を、エージェントが呼び出せる一連のMCPツールとして公開します。「クラスターを確認」を、コピー＆ペーストで祈るような行為から、実際の会話に変えます。

• 設計上読み取り専用。 applyもdeleteもexecもありません。サーバーは常に調査のみを行います。

• デフォルトでモックモード。 シードされた偽のクラスターが同梱されており、実際のクラスターなしで30秒で試せます。

• 準備ができたら実モード。 KUBECONFIGを指定すると、公式Kubernetes Pythonクライアントを介してライブクラスターを照会します。

Related MCP server: mcp-k8s-context-server

インストール

pip install kubectl-mcp                # mock mode (default)
pip install "kubectl-mcp[real]"        # + real-cluster support (kubernetes client)

またはソースから：

git clone https://github.com/teresa-tran/kubectl-mcp.git
cd kubectl-mcp
pip install -e ".[real,dev]"

スタンドアロンで実行（動作確認）

kubectl-mcp --help                     # show flags
kubectl-mcp --list-tools               # print every MCP tool + its schema
kubectl-mcp --demo list_pods           # run a tool once against the mock cluster
kubectl-mcp --demo find_restarted_pods --arg since_minutes=120

MCPクライアントに接続する

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（Mac）または%APPDATA%\Claude\claude_desktop_config.json（Windows）に追加：

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp"
    }
  }
}

実クラスターモードの場合：

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp",
      "env": {
        "KUBECTL_MCP_MODE": "real",
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Claude Desktopを再起動します。これで*「production名前空間のポッドを一覧表示」*と尋ねると、実際の回答が得られるはずです。

その他のMCP互換クライアント

stdio MCPを話すクライアント（Cursor、Cline、Continue、カスタムエージェントなど）はすべて同じように動作します。kubectl-mcpバイナリを指定するだけです。

公開ツール

すべてのツールにはJSON Schemaがあります。LLMは適切な引数検証を自動的に受けられます。

設定

環境変数：

モッククラスター

デフォルトのモッククラスターはsrc/kubectl_mcp/mock_data.jsonに同梱されており、以下が含まれます：

• 3つの名前空間：default、production、staging

• 正常、クラッシュループ、最近再起動した状態を含む約15個のポッド

• デプロイメント、サービス、最近のイベントのストリーム

• 一部のポッドは再起動回数が0より大きいため、find_restarted_podsは実際の結果を返します

特定のシナリオをデモしたい場合は、KUBECTL_MCP_MOCK_DATA=/path/to/your.jsonを設定して上書きできます。

設計ノート

• 構造的に読み取り専用。 KubernetesBackendプロトコルは読み取りメソッドのみを定義します。クラスター状態を変更できるコードパスはありません。実モードでも同様です。

• バックエンドは交換可能。 MockBackendとRealBackendは同じプロトコルを実装します。3つ目（例：キャッシュされたスナップショット）を追加するのは1ファイルです。

• エラーは例外であり、暗黙のnullではありません。 ResourceNotFound、NamespaceNotFoundなどは、エージェントが軌道修正できるように、役立つメッセージ付きのMcpErrorとして伝播します。

• stdioトランスポート。 すべてのMCPツール呼び出しは、MCP仕様に正確に従ったstdio上のJSON-RPCです。

開発

pip install -e ".[real,dev]"
pytest                                 # run tests
ruff check src tests                   # lint
kubectl-mcp --demo list_pods --arg namespace=production   # smoke test

ロードマップ

• シードデータ付きモックバックエンド

• kubernetes Pythonクライアントによる実バックエンド

• 読み取り専用ツールサーフェス

• CI/スモークテスト用のスタンドアロン--demoモード

• マルチクラスターサポート（--contextフラグ）

• メトリクスツール（metrics.k8s.ioによるCPU/メモリ）

• 高頻度クエリ用のオプションのキャッシュレイヤー

ライセンス

MIT © 2026 Teresa Tran