Proxmox Ops

proxmox-ops-mcp

Proxmox VE 向けの MCP サーバーです。クラスターで何が問題になっているのか、バックアップが実際に存在するのか、メンテナンスのためにノードを停止できるのかを確認するなど、運用作業のために構築されています。書き込みアクセスにも対応していますが、デフォルトでは無効で、変更のたびに明示的な追加の呼び出しが必要です。

Proxmox MCP サーバーをもうひとつ作った理由

既存のものは、主に API エンドポイントを個別に公開しています。「VM 104 を起動する」には十分ですが、「昨夜のバックアップがないゲストはどれか？」といった質問には何度も呼び出しが必要になり、モデルがそれらを正しく組み合わせるために Proxmox を十分に理解していなければなりません。通常、モデルはそこまで理解していません。たとえば、VM.Backup を持たないトークンではエラーではなく空のバックアップ一覧が返ることを知りません。

このサーバーでは、その知識をツールに組み込んでいます。backup_audit はバックアップボリュームを読み取り、vzdump ジョブと同じゲスト選択を適用して、トークンにボリュームを参照する権限があるかどうかを確認します。モデルには検出結果の一覧が返され、それぞれに安定したコードと推奨事項が含まれます。

ステータス

バージョン 0.1 です。使用できますが、まだ新しいプロジェクトです。テストした環境は次のとおりです。

Proxmox VE 9.2、単一ノード、ZFS、2 つのバックアップストレージ	すべての読み取りツール、すべての書き込みツール（専用プール内の使い捨て VM でテスト）
マルチノードクラスター、HA、Ceph	現実的なペイロードを使った単体テストと統合テストのみ
Proxmox VE 8、Proxmox Backup Server ストレージ	実環境では未テストです。報告をお待ちしています

実環境でのテストで、API ドキュメントに記載されていない点が 3 つ見つかりました。サーバーはそれぞれに対応しています。

• PVE 9 では、ノードステータス呼び出しで cpu と wait が 0 と報告されます。
• トークンに権限がない場合、バックアップ一覧はエラーにならず空で返されます。
• /cluster/resources は、実際のゲスト状態より数秒遅れます。

インストール

uvx proxmox-ops-mcp --version          # run without installing (uv)
pipx install proxmox-ops-mcp           # or as a CLI tool
docker pull ghcr.io/derdennis1012/proxmox-ops-mcp

Python 3.11 以降が必要です。ソースからインストールする場合：git clone … && uv sync && uv run proxmox-ops-mcp。

セットアップ

1. API トークンを作成します。 まずは読み取り専用にします。

pveum user add mcp@pve
pveum acl modify / --users mcp@pve --roles PVEAuditor
pveum user token add mcp@pve ops --privsep 1          # prints the secret once
pveum acl modify / --tokens 'mcp@pve!ops' --roles PVEAuditor

このロールだけでは、backup_audit からバックアップを参照できません。上位の権限レベルには、より多くの権限が必要です。また、Proxmox の ACL ルールにはいくつか注意点があります。どちらについてもdocs/proxmox-setup.mdで説明しています。

2. 接続を確認します。

$ export PROXMOX_HOST=pve1.example.com PROXMOX_TOKEN_ID='mcp@pve!ops' PROXMOX_TOKEN_SECRET=…
$ uvx proxmox-ops-mcp check
OK    connected to pve1.example.com:8006 as mcp@pve!ops
      Proxmox VE 9.2.5 (release 9.2)
      3 node(s) visible, access tier: read_only

これが SSLError で失敗する場合、ノードの証明書が使用しているアドレスをカバーしていない可能性があります。VPN 経由で接続するときによくある問題です。check を実行すると、証明書を固定するコマンドが表示されます。

3. クライアントに追加します。 Claude Code の場合：

claude mcp add proxmox-ops \
  -e PROXMOX_HOST=pve1.example.com \
  -e PROXMOX_TOKEN_ID='mcp@pve!ops' \
  -e PROXMOX_TOKEN_SECRET=… \
  -- uvx proxmox-ops-mcp

Claude Desktop、Cursor、VS Code、OpenAI Codex、Gemini CLI、Hermes Agent、OpenClaw、Docker については、docs/clients.mdをご覧ください。また、自律型エージェントがサーバーを使用するときの注意点も説明しています。

ツール

ツール	ティア
cluster_health	read_only	クォーラム、オフラインノード、CPU／メモリ、ストレージ使用率、HA エラー
ceph_health	read_only	ヒント付きの Ceph ヘルスチェック、OSD と PG の状態、モニタークォーラム、容量
compare_nodes	read_only	ノード間の I/O 待ち、負荷、スワップ、メモリ／I/O プレッシャー（PSI）、バージョンの差異
backup_audit	read_only	バックアップの欠落、古さ、未スケジュール、ジョブの失敗、PBS の検証
recent_task_failures	read_only	指定期間内に失敗したタスク
storage_health	read_only	ZFS プールの状態、デバイスとデータのエラー、スクラブ経過時間、SMART、SSD の摩耗
node_maintenance_status	read_only	保留中の Proxmox アップデート、必要な再起動、期限切れが近いノード証明書
recommend_placement	read_only	新しいゲストの配置先候補と、各ノードのスコアおよび理由
plan_node_evacuation	read_only	ノードを退避できるか、妨げる要因、実行するコマンド
list_nodes、list_guests、get_guest、get_task_status	read_only	インベントリ、ゲスト設定（シークレットはマスキング）、タスクログ
guest_power	operator	起動、シャットダウン、再起動。stop には admin が必要です
create_snapshot	operator	リスクのある変更の前にスナップショットを作成
migrate_guest	admin	VM のライブマイグレーション、コンテナーの再起動マイグレーション

パラメーターとすべての検出コードについては、docs/tools.md を参照してください。

plan_node_evacuation(node="pve1") の例（短縮版）：

{
  "feasible": true,
  "summary": "pve1 can be drained: 3 guests to 2 target nodes, 1 container(s) with a brief restart.",
  "guests": [
    { "vmid": 100, "name": "db01",  "mode": "ha-managed",            "target": "pve3" },
    { "vmid": 101, "name": "web01", "mode": "live-with-local-disks", "target": "pve2",
      "warnings": ["local disks will be copied: scsi0@local-lvm"] },
    { "vmid": 200, "name": "dns01", "mode": "restart",               "target": "pve3" }
  ],
  "steps": [
    "ceph osd set noout   # prevent rebalancing while the node is down",
    "ha-manager crm-command node-maintenance enable pve1   # HA moves its guests automatically",
    "qm migrate 101 pve2 --online --with-local-disks",
    "pct migrate 200 pve3 --restart",
    "# perform maintenance on pve1, reboot, verify it rejoined the cluster",
    "ha-manager crm-command node-maintenance disable pve1",
    "ceph osd unset noout"
  ]
}

書き込みアクセス

PROXMOX_ACCESS_TIER は変更しない限り read_only で、上位ティアのツールは 登録されません。書き込みツールは次の 2 段階で動作します。

1. 通常どおり呼び出すと、実際のゲスト状態に照らしてリクエストを確認し、実行内容の プレビューと確認トークンを返します。
2. 同じ引数とそのトークンを指定して再度呼び出すと、実行されます。

トークンは一度だけ使用でき、有効期限は 5 分で、指定されたパラメーターに厳密に紐づきます。 ノードもその対象となるため、その間にゲストが移行するとトークンは無効になります。書き込みは 名前付きプールまたは VMID に制限でき、1 時間あたりの上限も設定できます。すべてのプレビュー、 実行、拒否は監査ログに記録されます。

トークンにより、プレビューされた内容がそのまま実行されることを保証します。ただし、 モデルがトークンを参照できるため、ユーザーが承認したことの証明にはなりません。書き込みツールでは、 MCP クライアントのツール承認を有効にしておいてください。何かを削除するツールはありません。

HTTP トランスポートのデフォルト設定を含む詳細については、 docs/security-model.md を参照してください。

設定

PROXMOX_ プレフィックスの環境変数では、HOST、TOKEN_ID、TOKEN_SECRET が必須です。ACCESS_TIER、CA_BUNDLE または TLS_FINGERPRINT、AUDIT_LOG などは任意です。.env ファイルは --env-file を指定した場合にのみ読み込まれます。全項目の一覧は docs/configuration.md を参照してください。

開発

make install   # uv sync + pre-commit
make check     # ruff, mypy --strict, pytest

src/proxmox_ops_mcp/analysis/ の診断ロジックは、API ペイロードを処理する通常の関数で、 クラスターなしでテストされます。tests/live/ は、環境ファイルを指定すると実際のクラスターに対して 読み取り専用のチェックを実行します。docs/architecture.md では構成を、 CONTRIBUTING.md では貢献方法を説明しています。

ドキュメントサイト：https://derdennis1012.github.io/proxmox-ops-mcp/。今後の予定： Proxmox Backup Server の直接チェック（ガベージコレクション、プルーニング、検証ジョブ）、 レプリケーションジョブ、ゲストスナップショットの整理。

ライセンス

MIT。Proxmox は Proxmox Server Solutions GmbH の商標です。このプロジェクトは同社と 提携していません。