mcp-proxmox

mcp-proxmox

Claude、Cursor、Cline などの AI アシスタントを通じて Proxmox VE クラスターを管理する MCP サーバーです。

自然言語を使って、Proxmox インフラストラクチャ全体のプロビジョニング、管理、監視を行えます。VM やコンテナーの作成、スナップショットの管理、ストレージの閲覧などが可能です。

クイックスタート

# Run directly with uvx (no install needed)
uvx mcp-proxmox

# Or install with pip
pip install mcp-proxmox

設定

以下の環境変数を設定するか、.env ファイルを作成してください。

PROXMOX_HOST=192.168.1.100          # Your Proxmox VE host
PROXMOX_TOKEN_ID=user@pam!mcp       # API token ID
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # API token secret

任意の設定：

PROXMOX_PORT=8006                   # Default: 8006
PROXMOX_VERIFY_SSL=false            # Default: false

Proxmox API トークンの作成

1. Proxmox の Web UI にログインします
2. Datacenter > Permissions > API Tokens に移動します
3. Add をクリックし、ユーザー用のトークンを作成します
4. フルアクセスを許可するには「Privilege Separation」のチェックを外すか、特定の権限を割り当てます：
   • VM.Audit — VM/CT の状態と設定を読み取る
   • VM.PowerMgmt — 起動／停止／シャットダウン／再起動
   • VM.Snapshot — スナップショットの作成／ロールバック／削除
   • VM.Allocate — VM とコンテナーの作成／削除／クローン
   • VM.Clone — クローン操作
   • Datastore.Audit — ストレージの一覧表示とコンテンツの閲覧
   • Datastore.AllocateSpace — 新しい VM/CT 用のディスク領域の割り当て
   • Sys.Audit — ノードの状態とタスクを読み取る
   • VM.Config.Disk — ディスクのサイズ変更
   • VM.Config.CPU — CPU 割り当ての変更
   • VM.Config.Memory — メモリ割り当ての変更
   • VM.Monitor — QEMU モニターへのアクセス（メトリクス用）
   • VM.Console — コンソール操作ツール（スクリーンショット、キーボード入力）
   • VM.Migrate — ノード間での VM/CT の移行
   • Sys.Modify — ファイアウォールルールの管理
   • VM.Config.Cloudinit — cloud-init パラメーターの設定

統合

Claude Desktop

~/.claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "proxmox": {
      "command": "uvx",
      "args": ["mcp-proxmox"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "user@pam!mcp",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Claude Code

.claude/settings.json または ~/.claude/settings.json に追加します：

{
  "mcpServers": {
    "proxmox": {
      "command": "uvx",
      "args": ["mcp-proxmox"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "user@pam!mcp",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Cursor

上記と同じ設定を、Cursor Settings > MCP に追加します。

利用可能なツール

検出

Tool	Description
list_nodes	CPU、メモリ、稼働時間とともにクラスター内のすべてのノードを一覧表示
get_node_status	ノードの詳細情報：CPU モデル、メモリ、ディスク、バージョン
list_vms	QEMU VM を一覧表示（ノードまたは状態で絞り込み）
list_containers	LXC コンテナーを一覧表示（ノードまたは状態で絞り込み）
get_guest_status	VMID を指定して VM/CT の詳細な状態を取得（種類とノードを自動検出）

ライフサイクル

Tool	Description
start_guest	停止中の VM またはコンテナーを起動
stop_guest	強制停止（確認が必要）
shutdown_guest	ACPI/init による正常なシャットダウン
reboot_guest	再起動（確認が必要）

ストレージ

Tool	Description
list_storages	容量と使用量とともにストレージプールを一覧表示（ノードで絞り込み）
list_storage_content	ISO、テンプレート、バックアップ、ディスクイメージを閲覧

プロビジョニング

Tool	Description
create_vm	CPU、メモリ、ディスク、ISO、ネットワークを設定して QEMU VM を作成
create_container	テンプレートから LXC コンテナーを作成
clone_guest	VM または CT をクローン（フルクローンまたはリンククローン、ノード間に対応）
delete_guest	停止中の VM または CT を完全に削除（確認が必要）

バックアップと復元

Tool	Description
list_backups	バックアップファイルを一覧表示（ノード、ストレージ、VMID で絞り込み）
create_backup	vzdump バックアップを作成（snapshot/suspend/stop モード、zstd/lzo/gzip）
restore_backup	バックアップファイルから VM または CT を復元（確認が必要）

コマンド実行

Tool	Description
exec_command	ゲストエージェント経由で QEMU VM 内のコマンドを実行

注： exec_command を使うには、VM 内に qemu-guest-agent がインストールされ、実行中である必要があります。LXC コンテナーではサポートされていません（Proxmox API の制限）。

コンソール操作

ツール	説明
vm_screenshot	QEMU VM のディスプレイ（ログインプロンプト、起動メッセージ、インストーラー、GUI）の PNG スクリーンショットを撮影します
vm_send_key	VM コンソールにキーまたはキーの組み合わせを送信します（確認が必要です）
vm_send_text	VM コンソールに ASCII テキストを入力します（US 配列。確認が必要です）

注： コンソールツールには qemu-guest-agent は不要で、必要な権限は VM.Console のみです。vm_screenshot は Proxmox Web UI と同じ VNC WebSocket トンネル（DES ベースの VNC 認証を使用する RFB 3.8）を開き、標準ライブラリのみで実装されています（独自の WebSocket クライアント＋DES）。サポート対象は QEMU VM のみです。テキスト入力はキーボード配列に依存します。vm_send_text は ASCII を US キーボード配列に対応付けます（大文字や記号には Shift の対応付けを使用）。非 ASCII 入力（キリル文字など）は sendkey プロトコルではサポートされていません。

スナップショット

ツール	説明
list_snapshots	VM/CT のすべてのスナップショットを一覧表示します
create_snapshot	新しいスナップショットを作成します
rollback_snapshot	スナップショットにロールバックします（確認が必要です）
delete_snapshot	スナップショットを削除します（確認が必要です）

ネットワーク

ツール	説明
list_networks	ノード上のブリッジ、ボンド、物理インターフェイスを一覧表示します

サイズ変更

ツール	説明
resize_guest	VM またはコンテナの CPU、メモリ、ディスクのサイズを変更します（確認が必要です）

監視

ツール	説明
get_guest_metrics	CPU、メモリ、ネットワーク、ディスク I/O の経時データを取得します
list_tasks	ノード上の最近のタスク（バックアップ、移行など）を一覧表示します

ファイアウォール

ツール	説明
list_firewall_rules	VM/CT、ノード、またはクラスターのファイアウォールルールを一覧表示します
add_firewall_rule	ファイアウォールルールを追加します（アクション、方向、プロトコル、ポート、送信元／宛先）
delete_firewall_rule	位置を指定してファイアウォールルールを削除します（確認が必要です）

移行

ツール	説明
migrate_guest	VM/CT を別のノードにライブ移行またはオフライン移行します（確認が必要です）

テンプレートと Cloud-init

ツール	説明
list_templates	クローン作成に使用できるすべての VM テンプレートを一覧表示します
create_template	停止中の VM をテンプレートに変換します（確認が必要です。元に戻せません）
configure_cloud_init	VM のユーザー、パスワード、SSH キー、IP 設定、DNS を設定します

安全性

破壊的な操作（stop_guest、reboot_guest、rollback_snapshot、delete_snapshot、delete_guest、resize_guest、restore_backup、delete_firewall_rule、migrate_guest、create_template）には、明示的な confirm=true が必要です。最初の呼び出しでは影響を説明する警告が返されます。確認付きで 2 回目の呼び出しを行うと、操作が実行されます。

使用例

接続すると、AI アシスタントに次のように依頼できます。

• "すべての VM とそのステータスを一覧表示して"
• "VM 100 はメモリをどれくらい使用していますか？"
• "コンテナ 105 をシャットダウンして"
• "before-upgrade という名前で VM 200 のスナップショットを作成して"
• "過去 1 日間の VM 100 の CPU 使用率を表示して"
• "最近、ノード pve でどのタスクが実行されましたか？"
• "停止中の VM はどれですか？"
• "ストレージプールは何があり、それぞれの使用率はどれくらいですか？"
• "利用可能な ISO イメージを表示して"
• "4 コア、8GB RAM の新しい Ubuntu VM を作成して"
• "VM 100 をテスト環境としてクローンして"
• "テンプレートから Debian コンテナを作成して"
• "古いテスト VM 999 を削除して"
• "VM 100 を zfs-backup-storage にバックアップして"
• "VM 200 のバックアップをすべて表示して"
• "コンテナ 101 の最新のバックアップを復元して"
• "VM 100 で 'df -h' を実行して"
• "VM 200 で nginx が実行中か確認して"
• "コンソールを確認できるように、VM 100 のスクリーンショットを撮って"
• "VM がログインプロンプトで止まっています。'root' と入力して Enter キーを押して"
• "ノード pve のネットワークブリッジを表示して"
• "VM 100 の CPU を増やして、8 コアにして"
• "コンテナ 101 に 50GB のディスクを追加して"
• "VM 100 のファイアウォールルールを表示して"
• "コンテナ 101 で TCP ポート 443 を許可して"
• "VM 200 をノード pve2 に移行して"
• "クラスター内のテンプレートをすべて一覧表示して"
• "VM 102 をテンプレートに変換して"
• "VM 100 で cloud-init を設定して。ユーザーは admin、IP は dhcp、DNS は 8.8.8.8"

トラブルシューティング

Missing required environment variables

このエラーは、必要な接続設定の 1 つ以上がサーバープロセスで利用できないことを意味します。.env.example を .env にコピーし、PROXMOX_HOST、PROXMOX_TOKEN_ID、PROXMOX_TOKEN_SECRET を設定してください。MCP クライアントを直接設定する場合は、同じ変数がそのクライアントの env ブロックに含まれていることを確認してください。

403 Permission check failed

403 エラーは通常、API トークンは有効ですが、要求された操作に必要な Proxmox の権限が不足していることを意味します。Proxmox API トークンの作成を再確認し、完全なアクセスを許可するには「Privilege Separation」のチェックを外すか、そこに記載されている VM.Audit、VM.PowerMgmt、VM.Snapshot などの特定の権限、またはデータストア操作に必要なストレージ権限を割り当ててください。

exec_command がゲストエージェントまたは LXC に関する理由で失敗する

exec_command は、qemu-guest-agent がインストールされ、ゲスト内で実行されている QEMU VM でのみ動作します。QEMU ゲストエージェントが応答していないというツールのエラーが表示された場合は、VM にエージェントをインストールするか起動してから、もう一度試してください。この Proxmox API 経由では LXC コンテナはサポートされていないため、別のコンテナアクセス方法を使用してください。

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

MCP Python SDK 2.0 では、mcp-proxmox 1.2.1 以前がインポートする mcp.server.fastmcp モジュールが削除されました。新規インストール（uvx mcp-proxmox、uv tool install、pip install）では mcp 2.x が解決され、起動時に失敗していました。Claude Desktop では、この問題は「Server disconnected」としてのみ表示されます。mcp<2 を固定する mcp-proxmox 1.2.2 以降にアップグレードしてください。古い mcp-proxmox を使い続ける必要がある場合は、SDK のバージョンを自分で制限してください。uvx --with "mcp<2" mcp-proxmox。

自己署名証明書または接続エラー

Proxmox は通常ポート 8006 で動作するため、PROXMOX_HOST と PROXMOX_PORT が Proxmox の Web UI で使用するものと同じエンドポイントを指しているか確認してください。自己署名証明書を使用するホームラボクラスターでは、PROXMOX_VERIFY_SSL=false のままにするか、明示的に設定してください。PROXMOX_VERIFY_SSL=true を使用するのは、Proxmox の証明書が実行環境から信頼される CA につながっている場合に限ってください。

開発

git clone https://github.com/antonio-mello-ai/mcp-proxmox.git
cd mcp-proxmox
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/

ライセンス

MIT