Proxmox VE (Mojood Connect)

Proxmox VE MCP サーバー

Proxmox VE について、普段の言葉で Claude に質問できます。バックアップジョブの対象になっていないゲスト、バックアップの期限を過ぎているゲスト、停止中の本番 VM、特定の VM の状況などを確認できます。同じチャットからゲストの起動、シャットダウン、再起動、スナップショットの作成もできます。変更を加える前には確認ステップがあります。ゲストの削除、バックアップの復元、スナップショットのロールバックを行うツールはありません。

Mojood Connect が Proxmox の動作デモとして開発しました。API トークンを使い、REST API 経由で Proxmox VE 8 または 9 のいずれでも動作します。このリポジトリには、実際のクラスターに触れずに試せるよう、架空の会社 Harbor Trading のサンプルゲストを含む Proxmox VE 9.2（Proxmox 公式の arm64 ビルド。Apple Silicon Mac 上の VM 内で動作）をローカルにセットアップするスクリプトが含まれています。

ツール

ツール	内容	変更を加えますか？
overview	ノード（CPU、メモリ、稼働時間）、ストレージ使用量、実行中および停止中のゲスト、バックアップジョブ	いいえ
find_guests	名前、ID、タグ、状態で VM とコンテナーを検索し、使用中の CPU とメモリも表示します	いいえ
guest_details	1 つのゲストの詳細：コア、ディスク、メモ、スナップショット、最後のバックアップ、バックアップジョブの対象かどうか、最近のタスク（誰が何をしたか）	いいえ
needs_attention	バックアップジョブの対象外のゲスト、期限を過ぎたバックアップ、停止中の本番ゲスト、古いスナップショット、容量が逼迫しているストレージ、メモリが不足しているゲスト	いいえ
power_guest	VM またはコンテナーを起動、（正常に）シャットダウン、または再起動します	はい。確認後
snapshot_guest	誰からの依頼かを記したメモを添えてスナップショットを作成します	はい。確認後

変更を安全に行う方法。 confirmation を指定せずに power_guest または snapshot_guest を呼び出しても、何も変更されません。代わりに、平易な要約（「mail-relay（lima-pve 上の VM 104）を起動します。現在は停止中です。prod タグが付いています。」）と、一度限りのコードが返されます。同じリクエストをそのコードとともに 10 分以内に再度送信した場合にのみ、変更が実行されます。コードは一度だけ使用でき、発行されたリクエストに対してのみ有効です。サーバーの指示により、モデルは要約を提示してユーザーの承認を待ちます。Proxmox 自身のタスクログには、トークンのユーザー名で各変更が記録されます。

最小権限。 デモ用のトークンは、専用の Proxmox ユーザー claude@pve に属しています。このユーザーには、VM.Audit、VM.PowerMgmt、VM.Snapshot、Datastore.Audit、Sys.Audit のみを含むカスタムロールが割り当てられています。また、Proxmox ではバックアップできるユーザーにしかゲストのバックアップが表示されないため、VM.Backup と Datastore.AllocateSpace も付与されています（バックアップストレージのみ）。バックアップを作成、復元、削除するツールはありません。

ローカルで試す

ネストされた仮想化に対応した Apple Silicon Mac（M3 以降）、Lima、uv、 Python 3.13、約 6 GB の空きメモリ、40 GB のディスクが必要です。

scripts/reset.sh                         # Proxmox VE 9.2 in a Lima VM (first run installs it), filled with SAMPLE guests
uv run --env-file .env proxmox-mcp       # MCP server on http://127.0.0.1:8008/mcp (Streamable HTTP)

scripts/up.sh は、Proxmox のDebian 13 ガイドの手順で Proxmox VE をインストールし、VM とコンテナのスナップショットを作成できるように ZFS プール（ファイル上）を追加します。また、claude@pve ユーザーとそのトークン、Web UI（https://127.0.0.1:8006）用の読み取り専用 viewer@pve ユーザーを作成します。シークレットは Git で追跡されない .env にのみ保存され、出力されることはありません。ローカル証明書は自己署名のため、.env では PVE_VERIFY_TLS=0 に設定されています。実際のインストール環境では、この設定を有効にしてください。

Claude Desktop： パスをこのフォルダーに合わせて、claude_desktop_config.json（設定 › 開発者）に次の設定を追加してください。

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "--env-file", "/path/to/proxmox-mcp/.env", "proxmox-mcp", "--stdio"]
    }
  }
}

続いて、「バックアップされていないサーバーはどれですか？」「erp-app はどうなっていますか？」「今夜の更新前に erp-app のスナップショットを作成して、mail-relay を再起動してください。」と尋ねてください。

ご自身の Proxmox VE： 上記の権限を持つユーザーと API トークン（pveum user token add <user> <name> --privsep 0）を作成し、PVE_URL、PVE_TOKEN_ID（user@realm!name）、PVE_TOKEN_SECRET、PVE_SAMPLE=0 を設定してください。

SAMPLE ゲスト

Harbor Trading 用の VM 6 台（実際に起動する Alpine Linux）と LXC コンテナ 4 台です。ERP データベースとアプリサーバー、ファイルサーバー、停止したままのメールリレー、96 日前のスナップショットがある廃止済み CRM、ステージング用 Web サーバー、Web コンテナ 2 台、監視システム、VPN ゲートウェイが含まれます。夜間バックアップジョブはほとんどを対象にしていますが、すべてではありません。また、あるゲストの最新のバックアップは 9.9 日前のものです。バックアップとスナップショットは実際のものです。scripts/seed.sh は環境に履歴を持たせるため、一部のタイムスタンプを過去に変更します。内容はすべて架空です。

テスト

uv run --env-file .env pytest            # unit tests (a fake Proxmox API), plus live tests when the local Proxmox runs

本番バージョンで追加されるもの

このデモでは API トークンを 1 つ使用します。Proxmox のお客様向けの本番サーバーでは、各ユーザー自身の Proxmox アカウント（レルム、LDAP、または OpenID）でサインインできるようにし、Claude が各ユーザーのロールで許可された操作だけを実行できるようにします。さらに、複数ノードのクラスター、Proxmox Backup Server、すべてのツール呼び出しの監査ログを備えたホスティング、ディレクトリ一覧機能を追加します。Mojood Connect が構築しているのは、まさにこのような仕組みです。

ライセンス

Apache 2.0。Proxmox は Proxmox Server Solutions GmbH の登録商標です。このプロジェクトは Proxmox Server Solutions GmbH によって作成または承認されたものではありません。