proxmox-ve-mcp

1つ以上のProxmox VEホストをLLMクライアントが呼び出せるツールとして公開するMCPサーバーです。インベントリ（ノード、ゲスト、ストレージ、ネットワークブリッジ）、ライブステータスの読み取り、VMおよびコンテナの作成、クローン、起動、停止、削除が可能です。

Streamable HTTP上でMCPを話すため、ネットワーク上で独自のサービスとして動作し、単一クライアントのローカルサブプロセスとして動作するわけではありません。

universal-network-directorのために構築されました。これは、すべての書き込み操作に人間の承認ゲートを備えたチャット駆動型のマルチベンダーネットワークマネージャーです。ただし、これはスタンドアロンのMCPサーバーであり、任意のMCPクライアントで動作します。

Proxmox Server Solutions GmbHとは提携、承認、またはサポートされていません。 「Proxmox」および「Proxmox VE」は各所有者の商標であり、ここではこのソフトウェアが通信する対象を説明するためにのみ使用しています。

本番環境に適用する前に必ずお読みください

24のツールのうち12は状態を変更し、このサーバーは実行前に確認を求めません。 確認やドライランはありません。モデルが呼び出しを決定した場合は、そのまま実行されます。

これを処理する3つの方法を、実際に役立つ順に示します。

1. Proxmox APIトークンを読み取り専用にスコープする。 これが実際の制御であり、このコードではなくProxmox上にあります。トークンにビルトインのPVEAuditorロールをパス/で付与すると、モデルが何を決定しようと、すべての書き込みツールはAPIレベルで失敗します。書き込みを意図的に機能させたい場合を除き、これを実行してください。

2. 保護ゲスト拒否リストを使用する。 config/protected-vms.jsonは、書き込みツールが触れることを拒否するゲストをリストします。これはバックエンド呼び出しの前にローカルでチェックされるため、人間が誤って承認しても機能します。ファイルがないか解析できない場合、すべてのゲスト書き込みを拒否します（何も保護していないことを黙認するのではなく）。以下を参照してください。

3. クライアントで書き込みをゲートする。 すべての状態変更ツールにはwrite_プレフィックスが付いています。このプレフィックスは、クライアントがこれにマッチして、実行前に人間の承認ステップにそれらの呼び出しをルーティングできるようにするための、このコードベースの慣例です。このサーバーは意図的にそれを自分で行いません — 尋ねるユーザーがいないためです。

MCPエンドポイントには認証がありません

このサーバーは、そのポートに到達できる誰にでもツールを公開します。MCP側にはトークン、クライアント認証、TLSはありません。

MCP_HOSTはその理由でデフォルトで127.0.0.1になります。コンテナイメージは0.0.0.0に設定する必要があるため、コンテナのポートを公開すると、ハイパーバイザー用の認証なしのコントロールプレーンがそのインターフェースに公開されることになります。 内部ネットワークにクライアントと一緒に置くか、その前にTLSと認証を終端してください。

マルチホスト設計

Proxmoxクラスターは1つのAPIを共有しますが、多くのセットアップは異なるサブネット上で複数のスタンドアロンホストをクラスターなしで実行します。このサーバーは、短い自由形式のラベルでキー付けされた、ホストごとに1つの接続を保持し、すべてのツールはそのラベルを受け取ってどのホストと通信するかを選択します。

ホストは、1組の環境変数で定義されます。

PROXMOX_SERVER1_URL=https://pve1.example.com:8006
PROXMOX_SERVER1_TOKEN='automation@pve!mcp=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

PROXMOX_<LABEL>_URLの<LABEL>（小文字化）が、ツールが受け取るhost値になります（上記のserver1）。3番目のホストを追加するには、3番目の組を追加するだけです。コードの変更は不要です。モデルとログが明確に読めるように、サイトに合わせて名前を付けてください。

トークンはuser@realm!tokenid=secret文字列全体であり、作成時にDatacenter → Permissions → API Tokensで一度だけ表示されます。認証はステートレスです。すべてのリクエストはAuthorization: PVEAPIToken=...ヘッダーを運びます。ログイン呼び出しやCSRFトークンはありません — これはユーザー名/パスワードのセッションパスであり、ここでは意図的に使用していません。

自己署名証明書を持つホストにはPROXMOX_VERIFY_TLS=falseを設定します。デフォルトはオンです。

保護ゲスト拒否リスト

config/protected-vms.jsonは読み取り専用でコンテナにマウントされ、書き込みツールが絶対に触れてはいけないゲストを保持します。

{
  "protected_vms": [
    {
      "host": "server1",
      "vmid": 100,
      "name": "example-mcp-host",
      "reason": "EXAMPLE -- the VM this MCP server itself runs in"
    }
  ]
}

hostはlist_hostsからのラベルであり、Proxmoxノード名ではありません。reasonは拒否メッセージにそのまま表示されるため、それに遭遇した人のために記述してください。

このファイルはgitで追跡することを意図しています。元々は追跡されていない.envの環境変数として始まりましたが、これは新規クローンで保護が持続せず、空のリストが入力済みのリストとまったく同じに見えることを意味しました。現在は、ファイルがないか解析できない場合、すべてのゲスト書き込みを拒否します。空のリストは許可されますが、起動時に大きな警告をログに記録します。

ここに同梱されているエントリは例です。大切なものに適用する前に、これらを置き換えてください。

実行方法

docker build -t proxmox-ve-mcp .
docker run --rm \
  -e PROXMOX_SERVER1_URL=https://pve1.example.com:8006 \
  -e PROXMOX_SERVER1_TOKEN='automation@pve!mcp=...' \
  -e PROXMOX_VERIFY_TLS=false \
  -v "$PWD/config/protected-vms.json:/app/config/protected-vms.json:ro" \
  -p 127.0.0.1:8002:8002 \
  proxmox-ve-mcp

または、pip install -r requirements.txtをvirtualenvに対して実行し、python server.pyを直接実行します。

テスト

スタンドアロンスクリプト、pytestは使用しません。クライアントが必要とするPROXMOX_*環境が利用できるように、コンテナ内で実行します。

docker run --rm proxmox-ve-mcp python test_network_bridges.py
docker run --rm proxmox-ve-mcp python test_media_in_use.py
docker run --rm proxmox-ve-mcp python test_client.py

オフラインセクションは、架空のインターフェースリストとゲストリストを使用し、ホストが設定されていなくてもパスします。ライブセクションは、PROXMOX_*変数が指すものを読み取り、何も設定されていない場合はクリーンにスキップします — 実際のホストを指定して、偽造できない唯一の区別（ブリッジがアップリンクされているか、分離されているか）をテストします。

設計メモ

• /cluster/resourcesがインベントリのバックボーンです。 1回の呼び出しで、すべてのVM、コンテナ、ノード、ストレージがすでにノード、vmid、タイプでタグ付けされて返されます。スタンドアロンホストでも機能するため（その1つのノードを報告します）、/nodes → /nodes/{node}/qemuをノードごとにたどる代わりにこれを使用します。

• list_network_bridgesは、NICが間違ったブリッジにあるとゲストに到達できなくなるために存在します。 ブリッジごとに、メンバーポート（ボックスから出る方法）があるか、分離されたセグメントであるかを報告します。これは、新しいVMが到達可能になるかどうかを決定する区別です。

• VLANタグはフェイルクローズします。 bridge_vlan_awareでないブリッジにtag=を設定すると、Proxmoxは受け入れますが、その後静かにタグを運びません — 分離が要求された場所でタグなしトラフィックが流れます。書き込みパスは警告ではなく拒否し、ブリッジリストを読み取ってチェックできない場合も拒否します。

• 書き込みは非同期です。 ほとんどはProxmox UPIDを返します。完了を想定するのではなく、get_task_statusでポーリングしてください。

• ゲスト書き込みは1つのガードの背後で動作します。 単一のラッパーが保護VMチェックとvmid→ノード/種類の解決を行い、個々のツールがガードを忘れたり、保護されたゲストに対してバックエンドに到達したりすることができません。

ライセンス

Apache-2.0。 LICENSEを参照してください。