MCP Proxmox

🚀 MCP Proxmox Server

Pythonで実装された高度なProxmoxモデルコンテキストプロトコル（MCP）サーバーです。Proxmoxの発見、ライフサイクル管理、ネットワーク設定、スナップショット/バックアップ、メトリクス収集、プール/パーミッション管理、オーケストレーションなど、豊富なユーティリティを提供します。

• ガイドリファレンス: MCP Quickstart (Python)
• 構造のミラー: bsahane/mcp-ansible

🚀 クイックスタート

git clone https://github.com/bsahane/mcp-proxmox.git
cd mcp-proxmox

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt

# (オプション) パッケージをローカルにインストール
pip install -e .

📦 インストール

.envの設定

• .env.example を .env にコピーして値を編集します。

cp .env.example .env

.env のキー:

PROXMOX_API_URL="https://proxmox.example.com:8006"
PROXMOX_TOKEN_ID="root@pam!mcp-proxmox"
PROXMOX_TOKEN_SECRET="<secret>"
PROXMOX_VERIFY="true"
PROXMOX_DEFAULT_NODE="pve"
PROXMOX_DEFAULT_STORAGE="local-lvm"
PROXMOX_DEFAULT_BRIDGE="vmbr0"

注意事項:

• 適切なACLを持つAPIトークンを使用してください。発見には、 / での PVEAuditor で十分です。ライフサイクル管理には、プール上でより狭いロール（例: PVEVMAdmin）を付与します。
• .env を使用することで、トークンIDに ! が含まれる場合のzsh履歴展開の問題を回避できます。

MCPサーバーの実行 (stdio)

推奨（モジュール形式）:

source .venv/bin/activate
python -m proxmox_mcp.server

またはインストールされたコンソールスクリプト:

source .venv/bin/activate
proxmox-mcp

Cursorでの設定

~/.cursor/mcp.json を編集します（ポータブルな例）:

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

Claude for Desktopでの設定

~/Library/Application Support/Claude/claude_desktop_config.json に追加します:

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

💻 使用例

基本的な使用法

• ノードの一覧を取得: {} を proxmox-list-nodes に渡します。
• ノード pve 上のVMを一覧表示: { "node": "pve" } を proxmox-list-vms に渡します。
• テンプレートをクローン: { "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true } を proxmox-clone-vm に渡します。
• Cloud-initのIPを設定: { "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true } を proxmox-cloudinit-set に渡します。

📚 ドキュメント

ツールリファレンス

すべてのツールはMCPを通じて利用できます。破壊的なツールは confirm を受け入れ、ほとんどの書き込み操作は dry_run、wait、timeout、poll_interval をサポートします。 以下は各ツールの形式です:

• 説明
• 例の質問 → 可能な回答（形式）

コア発見

• proxmox-list-nodes
  • クラスターノードの一覧を表示（名前、ステータス、CPU/RAM/ディスクの概要）
  • 例: "List cluster nodes"
  • 回答: [ { "node": "pve", "status": "online", ... } ]
• proxmox-node-status
  • ノードの詳細なヘルス状態（負荷、稼働時間、バージョン）
  • 例: { "node": "pve" }
  • 回答: { "kversion": "...", "uptime": 123456, ... }
• proxmox-list-vms
  • VMの一覧を表示（ノード、ステータス、名前の部分文字列でフィルタリング）
  • 例: { "node": "pve", "status": "running" }
  • 回答: [ { "vmid": 100, "name": "web01", ... } ]
• proxmox-vm-info
  • vmid または name（オプションでノード）でVMの詳細を取得します。設定も含まれます。
  • 例: { "name": "web01" }
  • 回答: { "selector": {...}, "config": {...} }
• proxmox-list-lxc
  • LXCコンテナの一覧を表示（フィルタリング可能）
  • 例: { "node": "pve" }
  • 回答: [ { "vmid": 50001, "name": "ct01", ... } ]
• proxmox-lxc-info
  • vmid または name（オプションでノード）でLXCの詳細を取得します。
  • 例: { "vmid": 50001 }
  • 回答: { "selector": {...}, "config": {...} }
• proxmox-list-storage
  • ストレージの一覧を表示（タイプ、空き容量/使用容量）
  • 例: {}
  • 回答: [ { "storage": "local-lvm", "type": "lvmthin", ... } ]
• proxmox-storage-content
  • ストレージの内容（ISO、テンプレート、イメージ）の一覧を表示
  • 例: { "node": "pve", "storage": "local" }
  • 回答: [ { "volid": "local:iso/foo.iso", ... } ]
• proxmox-list-bridges
  • ノードのブリッジ（vmbr...）の一覧を表示
  • 例: { "node": "pve" }
  • 回答: [ { "iface": "vmbr0", ... } ]
• proxmox-list-tasks
  • 最近のタスク（ノード、ユーザーでフィルタリング）
  • 例: { "node": "pve", "limit": 20 }
  • 回答: [ { "upid": "UPID:...", "status": "OK" }, ... ]
• proxmox-task-status
  • タスクのステータスを確認
  • 例: { "upid": "UPID:..." }
  • 回答: { "status": "stopped", "exitstatus": "OK" }

VMライフサイクル

• proxmox-clone-vm
  • テンプレートVMを新しいVMID/名前にクローンします（ターゲットノード、ストレージをサポート）
  • 例: { "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true }
  • 回答: { "upid": "UPID:...", "status": {...} }
• proxmox-create-vm
  • ISO/テンプレートから新しいVMを作成します（最小限の設定）
  • 例: { "node": "pve", "vmid": 200, "name": "web02", "iso": "debian.iso", "confirm": true }
  • 回答: { "upid": "UPID:..." }
• proxmox-delete-vm
  • VMを削除します（確認、完全削除）
  • 例: { "name": "web01", "purge": true, "confirm": true }
  • 回答: { "upid": "UPID:..." }
• proxmox-start-vm / proxmox-stop-vm / proxmox-reboot-vm / proxmox-shutdown-vm
  • 電源状態を管理します（停止はハード停止とタイムアウトをサポート）
  • 例: { "name": "web01", "wait": true }
  • 回答: { "upid": "UPID:...", "status": {...} }
• proxmox-migrate-vm
  • 別のノードにライブ/オフラインで移行します
  • 例: { "name": "web01", "target_node": "pve2", "live": true }
  • 回答: { "upid": "UPID:..." }
• proxmox-resize-vm-disk
  • ターゲットディスク（例: scsi0）のディスク容量を拡張します（GB）
  • 例: { "name": "web01", "disk": "scsi0", "grow_gb": 10, "confirm": true, "wait": true }
  • 回答: { "upid": "UPID:...", "status": {...} }
• proxmox-configure-vm
  • ホワイトリストされたパラメータ（コア数、メモリ、バルーン、ネットワークインターフェイス、エージェントなど）を設定します。
  • 例: { "name": "web01", "params": { "memory": 4096, "cores": 4 }, "confirm": true }
  • 回答: { "upid": "UPID:..." } または { "result": null }

LXCライフサイクル

• proxmox-create-lxc
  • テンプレートからコンテナを作成します（CPU/メモリ、ルートファイルシステムのサイズ、ネットワーク、ストレージ）
  • 例: { "node": "pve", "vmid": 50050, "hostname": "ct01", "ostemplate": "debian-12.tar.zst", "confirm": true }
  • 回答: { "upid": "UPID:..." }
• proxmox-delete-lxc / proxmox-start-lxc / proxmox-stop-lxc / proxmox-configure-lxc
  • コンテナのライフサイクルと設定を管理します。

Cloud-initとネットワーク

• proxmox-cloudinit-set
  • CIパラメータ（ipconfig0、sshキー、ciユーザー/パスワード）を設定します。
  • 例: { "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true }
  • 回答: { "upid": "UPID:..." } または { "result": null }
• proxmox-vm-nic-add / proxmox-vm-nic-remove
  • NICを追加/削除します（ブリッジ、モデル、VLAN）
• proxmox-vm-firewall-get / proxmox-vm-firewall-set
  • 各VMのファイアウォールの状態とルールを取得/設定します。

イメージ、テンプレート、スナップショット、バックアップ

• proxmox-upload-iso / proxmox-upload-template
  • ISOまたはLXCテンプレートをストレージにアップロードします。
• proxmox-template-vm
  • VMをテンプレートに変換します。
• proxmox-list-snapshots / proxmox-create-snapshot / proxmox-delete-snapshot / proxmox-rollback-snapshot
  • スナップショットを管理します。ロールバックは wait をサポートします。
• proxmox-backup-vm / proxmox-restore-vm
  • vzdumpを実行し、アーカイブを復元します。

メトリクスとモニタリング

• proxmox-vm-metrics
  • VMのRRDメトリクス（時間範囲、CF）
• proxmox-node-metrics
  • ノードのRRDメトリクス

プール、ユーザー、パーミッション

• proxmox-list-pools / proxmox-create-pool / proxmox-delete-pool / proxmox-pool-add / proxmox-pool-remove
• proxmox-list-users / proxmox-list-roles / proxmox-assign-permission

オーケストレーションヘルパー

• proxmox-wait-task
  • タスクが完了するかタイムアウトするまでポーリングします。
• proxmox-register-vm-as-host
  • AnsibleインベントリのJSON/INIスニペットを生成します（ホスト名、IP、SSHユーザー/キー）
• proxmox-guest-exec (オプション)
  • QEMUゲストエージェントを介してコマンドを実行します（ゲストにエージェントが必要）

🔧 技術詳細

• サーバーはstdioトランスポートを使用します。標準出力にはMCPプロトコルのみを出力します。ログは標準エラー出力に出力されます。
• 認証には環境変数および/または .env ファイルを使用します。
• ノード間で名前が重複する場合、node を指定しない限り明確なエラーが返されます。

📄 ライセンス

MIT