RekklesNA/ProxmoxMCP-Plus

Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.

概要: ProxmoxMCP-Plusは、AIアシスタント（および通常のHTTPツール）がProxmox VE仮想化サーバーを操作できるようにする制御レイヤーです。VMの作成、Linuxコンテナ(LXC)の管理、スナップショットの取得、バックアップの実行、ISOの取得などを、統一されたセキュリティ意識の高いインターフェースを通じて行えます。生のProxmox API呼び出しやシェルスクリプトを手書きする代わりに、オペレーターはこのサーバーを一度セットアップし、ツールをそこに向けるだけで済みます。

解決する課題

Proxmox VEは、仮想マシンやコンテナをホストする基盤システムです。通常、タスクを自動化するには、生のAPI呼び出し、アドホックなスクリプト、カスタムのジョブポーリングループを組み合わせる必要があります。このプロジェクトは、その継ぎはぎを、2つの業界標準言語を話す単一のツールに置き換えます。

MCP (Model Context Protocol): Claude Desktop、Cursor、VS Code、Open WebUIなどのAIエージェントが外部ツールと通信する方法。これが「AIクライアント」パスです。
OpenAPI (REST/HTTP): 従来のダッシュボード、内部スクリプト、ノーコード自動化プラットフォームがサービスを呼び出す方法。これが「標準HTTP」パスです。

両方のパスが同じワークフローに供給されるため、2つの異なるシステムを学習することなく、一方（または両方）を使用できます。

実際の機能

READMEによると、操作範囲には以下が含まれます:

VMおよびLXCのライフサイクルアクション — 仮想マシンやコンテナの起動、停止、作成、削除
スナップショット — 作成、ロールバック、削除
バックアップおよびリストアワークフロー
ISOのダウンロードとクリーンアップ — インストールイメージの取得と古いイメージの削除
ノード、ストレージ、クラスターの検査 — ハイパーバイザーとその環境の健全性と状態の確認
SSHベースのコンテナコマンド — ガードレール付きでコンテナ内でコマンドを実行（オプション、SSH設定が必要）
オプトインの保護されたノードSSHコマンド — Proxmoxホスト自体でコマンドを実行（同様に保護され、オプトイン）
永続的なジョブ追跡 — 長時間実行されるProxmoxタスクは安定したジョブID (job_id) を取得し、Proxmoxの UPID を追跡し、ポーリング、再試行、キャンセル、監査履歴をサポートします

実行方法

READMEには3つの主要な実行パスが記載されています:

PyPIからのMCP stdio — ローカルAIクライアント（Claude Desktop、Cursor、VS Code）向けの古典的な方法。uvx proxmox-mcp-plus または pip install proxmox-mcp-plus で起動します。
Docker経由のネイティブMCP HTTP — 「Streamable HTTP」トランスポートをサポートするリモートMCPクライアント向け。ポート 8000 の /mcp で起動し、MCP_API_KEY によるAPIキーが必要です。
Docker経由のOpenAPIブリッジ — デフォルトのDockerモード。ポート 8811 でRESTエンドポイントを提供し、PROXMOX_API_KEY で保護されます。ヘルスエンドポイントは /livez、仕様は /openapi.json にあります。

これらを実行する前に、Proxmox APIトークンを作成し、proxmox-config/config.example.json を proxmox-config/config.json にコピーして、ホスト、ポート、ユーザー、トークンの詳細を入力します。（オプションで ssh および jobs セクションを追加します。）

セキュリティ機能

READMEでは「セキュリティ意識の高い」設計が強調されています:

Proxmox用APIトークン（最小権限）
OpenAPIブリッジ用Bearerトークン認証
コマンドポリシー — 許可されるコンテナ/ホストコマンドを管理するルール
承認トークン — 特定のアクションに対して明示的な人間の承認を要求可能
TLS検証 — デフォルトでSSL証明書を検証
MCP HTTPホスト/オリジン制御 — DNSリバインディング保護および許可リスト化されたオリジン
ツール公開フィルタリング — サーバーがクライアントに送信するツールスキーマを制限するオプションの許可リスト/拒否リスト。空のリストはすべてを無効にし、不明な名前は起動に失敗し、正確な小文字の名前のみが機能します

コードモード (オプトイン)

デフォルトでは、サーバーはツールの全カタログを公開します。mcp.code_mode: true (または MCP_CODE_MODE=true) を設定すると、代わりに 3つのツールに切り替わります:

proxmox_code_search — 利用可能なものを発見
proxmox_code_get_schema — 引数スキーマを取得
proxmox_code_execute — ドメインツールに対してスクリプト化された式を実行

コード実行は分離されたサンドボックス内で実行され（登録されたツール呼び出し以外、ファイルシステムやネットワークアクセスは不可）、厳しい制限があります：64,000ソース文字、100MBメモリ、25ツール呼び出し、16KBの最終JSON、2つの同時実行、30秒の予算。スクリプトのキャンセルや失敗はツールの副作用をロールバックしません。そのため、失敗した変更を自動的に再試行すべきではありません。オプションのワーカープール再利用が可能です (mcp.code_mode_pool_reuse)。

OAuthブラウザゲート (オプション、ネイティブMCP HTTP)

リモートMCPクライアント向けのより洗練された認証フローです。生のAPIキーを送信する代わりに、ユーザーはPKCE（安全なログイン標準）を使用したOAuth認可コードフローを通過します。人間が必要な唯一の資格情報は MCP_API_KEY です。ブラウザは同意ページにアクセスし、クライアントが何を求めているかを確認し、キーを入力します。OAuth状態は（ローカルファイルではなく）PostgreSQLに保存されるため、複数のサーバーインスタンスが安全に状態を共有できます。サーバーはプロトコルエンドポイントにMCP Python SDKを使用し、同意ページとAPIキーポリシーを追加します。

MCP_OAUTH_ENABLED=true を切り替える際の重要な要件: MCP_OAUTH_ISSUER (パブリックHTTPSオリジン)、MCP_OAUTH_DATABASE_URL (PostgreSQL DSN)、および MCP_API_KEY。OAuthが有効な場合、生の Authorization: Bearer <key> リクエストは拒否され、発行されたOAuthトークンのみが機能します。

違い (プロジェクト独自の表より)

優先度	アプローチ
デュアルアクセスパス	同じワークフローでネイティブMCP + OpenAPI
Proxmox指向	基本を超えたDay-2運用: スナップショット、バックアップ、ISO、ストレージ、クラスター
長時間実行作業	安定したジョブID、UPID追跡、ポーリング、再試行、キャンセル、監査証跡
より安全な実行	トークン、コマンドポリシー、承認、TLS検証、ホスト/オリジン制御
実際の検証	ユニット、統合、Docker/OpenAPI、およびライブProxmoxテスト（リポジトリに文書化）

結論

Proxmox VEクラスターを運用しており、AIエージェントやHTTP自動化で安全に管理したい場合、このプロジェクトは2つのインターフェース、強力なセキュリティ体制、Proxmox特有の非同期タスクに対する堅牢なジョブ追跡を備えたインストール可能なブリッジを提供します。JSONファイルと環境変数で構成可能で、PyPIまたはDockerから実行でき、自律型エージェントがインフラストラクチャに触れる際の穏やかなガードレール（許可リスト、承認、サンドボックス）が含まれています。