🚀 Proxmox MCP Server (Node.js Edition)

Proxmox MCP Server（Node.js 版）

Proxmox VE ハイパーバイザー（ノード、QEMU VM、LXC コンテナー）を管理する、Node.js ベースの Model Context Protocol（MCP）サーバーです。権限レベルを設定でき、Terraform/OpenTofu へのエクスポートにも対応しています。

クレジット

canvrno/ProxmoxMCP によるオリジナルの Python 実装をベースにしています。この Node.js 版は、権限管理の設定機能と Terraform/OpenTofu 生成機能を追加しながら、同じコア機能を維持しています。

機能

• 2 つの権限レベル：デフォルトは読み取り専用です。破壊的操作を行うには、明示的にオプトインする必要があります（PROXMOX_ALLOW_ELEVATED=true）
• ノード、VM、コンテナーの管理：ステータス、ライフサイクル（起動／停止／再起動／シャットダウン／一時停止）、作成、クローン、サイズ変更、削除、移行、テンプレートへの変換
• タスクの追跡：UPID を指定して任意のタスクを読み取り（必要に応じて完了を待機し）、変更操作が実際に完了したことを確認できます
• ゲストエージェント連携：コマンドを実行して標準出力／終了コードを読み取り、実行中の VM の実際の IP アドレスを検出できます
• スナップショットとバックアップ：作成、一覧表示、ロールバック、削除
• ディスクとネットワークの設定：ディスク、マウントポイント、ネットワークインターフェイスの追加、サイズ変更、移動、削除
• Cloud-init、過去のメトリクス（RRD）、プール、HA リソース、ファイアウォールルールの読み取り専用の可観測性
• Terraform/OpenTofu エクスポート：既存の VM とコンテナーから HCL（import ブロックを含む）を生成し、再作成せずに IaC へ取り込めます
• 構造化出力：ツールは Markdown テキストに加えて、機械可読な structuredContent を返すため、エージェントはデータを連鎖的に処理できます
• MCP リソース（proxmox://nodes、proxmox://vms、proxmox://storage）とプロンプト（プロビジョニング、ヘルスチェック、権限の診断）
• 安全策：TLS 検証の任意設定、ノード／VMID の許可リスト、保護されたゲストの削除を阻止する保護フラグのチェック
• 公式 MCP SDK を基盤として構築

インストール

前提条件

• Node.js 20 以降と npm
• Proxmox VE サーバーと API トークン（API トークンの設定を参照）

セットアップ

クローンしてインストールします：

git clone https://github.com/gilby125/mcp-proxmox.git
cd mcp-proxmox
npm install

クローンせずに npx で実行することもできます：

PROXMOX_HOST=your-proxmox-ip PROXMOX_TOKEN_VALUE=your-token-secret npx mcp-proxmox

Docker を使用する場合（MCP は stdio 経由で通信するため、-i を付けてアタッチして実行します）：

docker build -t mcp-proxmox .
docker run -i --rm \
  -e PROXMOX_HOST=your-proxmox-ip \
  -e PROXMOX_TOKEN_VALUE=your-token-secret \
  mcp-proxmox

設定

サーバーは環境変数のみで設定します：

変数	必須	デフォルト	説明
PROXMOX_HOST	はい	—	Proxmox の IP アドレスまたはホスト名
PROXMOX_TOKEN_VALUE	はい	—	API トークンのシークレット
PROXMOX_USER	いいえ	root@pam	トークンが属するユーザー
PROXMOX_TOKEN_NAME	いいえ	mcpserver	API トークン ID
PROXMOX_PORT	いいえ	8006	Proxmox API ポート
PROXMOX_ALLOW_ELEVATED	いいえ	false	書き込み／破壊的操作のツールを有効にするには true に設定
PROXMOX_VERIFY_TLS	いいえ	false	Proxmox の TLS 証明書を検証するには true に設定（CA 署名済み証明書を使用してください）
PROXMOX_NODE_ALLOWLIST	いいえ	—	サーバーが操作できるノード名をカンマ区切りで指定します。空欄の場合は制限なしです
PROXMOX_VMID_ALLOWLIST	いいえ	—	サーバーが操作できる VMID をカンマ区切りで指定します。空欄の場合は制限なしです

設定値の指定方法は 2 通りあります：

方法 1：MCP クライアント設定の env ブロック（推奨）

Claude Desktop の場合、設定ファイルを編集します（macOS：~/Library/Application Support/Claude/claude_desktop_config.json、Linux：~/.config/Claude/claude_desktop_config.json、Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-proxmox/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-ip",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-server",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_ALLOW_ELEVATED": "false"
      }
    }
  }
}

編集後にクライアントを再起動し、「Proxmox VM を一覧表示して」と尋ねてテストします。

方法 2：インストール先の親ディレクトリに .env ファイルを配置

サーバーは index.js からの相対パス ../.env、つまりクローンしたリポジトリの 1 つ上のディレクトリから .env を読み込みます（シークレットがコミットされないよう、リポジトリの外に配置します）：

/home/user/
├── .env             <- environment file goes here
└── mcp-proxmox/
    └── index.js     <- loads ../.env from here

# /home/user/.env
PROXMOX_HOST=your-proxmox-ip-or-hostname
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=mcp-server
PROXMOX_TOKEN_VALUE=your-token-secret
PROXMOX_ALLOW_ELEVATED=false

Proxmox API トークンの設定

1. Proxmox Web UI -> Datacenter -> Permissions -> API Tokens -> Add
2. ユーザー（例：root@pam）とトークン ID（例：mcp-server）を選択します
3. シークレットはすぐにコピーしてください。表示されるのは一度だけです
4. トークン ID を PROXMOX_TOKEN_NAME に、シークレットを PROXMOX_TOKEN_VALUE に設定します

権限：基本（読み取り専用）モードは、最小限のトークン権限で動作します。昇格モードでは、使用するツールに応じて、Sys.Audit、VM.Monitor、VM.Console、VM.Allocate、VM.PowerMgmt、VM.Snapshot、VM.Backup、VM.Config.*、Datastore.Audit、Datastore.Allocate を含むロールが必要です。

権限レベル

基本モード（デフォルトの PROXMOX_ALLOW_ELEVATED=false）では、ノード、VM、コンテナー、ストレージ、クラスターの状態、テンプレートの一覧表示と Terraform の生成のみが可能です。

昇格モード（PROXMOX_ALLOW_ELEVATED=true）では、VM、コンテナー、スナップショット、バックアップ、ディスク、ネットワークインターフェースの作成、変更、完全削除、およびゲスト内でのコマンド実行を行う書き込みツールも有効になります。こうしたリスクを理解し、受け入れる場合にのみ有効にしてください。

利用可能なツール

読み取り専用（常に利用可能）

ツール	説明
proxmox_get_nodes	クラスターのノードと状態およびリソースを一覧表示します
proxmox_get_node_status	ノードの詳細な状態（昇格権限と Sys.Audit が必要）
proxmox_get_vms	VM／コンテナーを一覧表示します。ノードとタイプで絞り込めます
proxmox_get_vm_status	1 つの VM／コンテナーの詳細な状態
proxmox_get_storage	ストレージプールと使用状況を一覧表示します
proxmox_get_cluster_status	クラスターの健全性の概要
proxmox_list_templates	ストレージ上の LXC テンプレートを一覧表示します
proxmox_get_next_vmid	次に利用可能な VM／コンテナー ID
proxmox_get_vm_config	VM／コンテナーの完全な設定（コア、メモリ、ディスク、ネットワーク、cloud-init）
proxmox_get_task_status	UPID でタスクの状態を取得します。完了まで待機することもできます
proxmox_whoami	トークンの認証先の ID と有効な権限
proxmox_get_rrd_data	CPU／メモリ／ディスク／ネットワークの履歴時系列データ（ノードまたはゲスト）
proxmox_get_pools	リソースプールとそのメンバー
proxmox_get_ha_resources	高可用性リソースと目標状態
proxmox_get_firewall_rules	クラスター／ノード／ゲストレベルのファイアウォールルール
proxmox_generate_terraform	既存のゲストから Terraform／OpenTofu HCL を生成します

昇格（PROXMOX_ALLOW_ELEVATED=true が必要）

カテゴリ	ツール
作成	proxmox_create_vm、proxmox_create_lxc
ライフサイクル	proxmox_start_*、proxmox_stop_*、proxmox_reboot_*、proxmox_shutdown_*、proxmox_pause_vm、proxmox_resume_vm
クローン／サイズ変更／削除	proxmox_clone_*、proxmox_resize_*、proxmox_delete_*
スナップショット	proxmox_create_snapshot_*、proxmox_list_snapshots_*、proxmox_rollback_snapshot_*、proxmox_delete_snapshot_*
バックアップ	proxmox_create_backup_*、proxmox_list_backups、proxmox_restore_backup_*、proxmox_delete_backup
ディスク	proxmox_add_disk_vm、proxmox_add_mountpoint_lxc、proxmox_resize_disk_*、proxmox_remove_disk_vm、proxmox_remove_mountpoint_lxc、proxmox_move_disk_*
ネットワーク	proxmox_add_network_*、proxmox_update_network_*、proxmox_remove_network_*
移行／テンプレート	proxmox_migrate_vm、proxmox_convert_to_template
Cloud-init	proxmox_set_cloudinit（QEMU）
ゲスト実行／IP	proxmox_execute_vm_command、proxmox_get_guest_ips（ゲストエージェント経由の QEMU）

_* サフィックスが付くツールには、_vm（QEMU）と _lxc（コンテナー）のバリアントがあります。

proxmox_execute_vm_command はデフォルトでゲストエージェントをポーリングし（wait: true）、コマンドの stdout、stderr、終了コードを返します。PID のみを返すには wait: false を指定します。proxmox_migrate_vm などの長時間実行される操作はタスク UPID を返します。完了を確認するには、この UPID を proxmox_get_task_status に渡し、wait: true を指定してください。

Terraform/OpenTofu エクスポート

proxmox_generate_terraform は既存の VM とコンテナの稼働中の構成を読み取り、bpg/proxmox プロバイダー用の HCL を生成します。import ブロックも含まれるため、terraform plan / tofu plan は実行中のゲストを再作成せずに取り込みます。

引数（すべて省略可能）：

• node — このノード上のゲストのみをエクスポートします
• vmid — 単一の VM／コンテナをエクスポートします
• type — qemu、lxc、または all（デフォルト）
• include_provider — terraform {} / provider {} のひな型を含めます（デフォルトは true）

プロンプトの例：「ノード pve1 上の VM 100 の terraform を生成してください」。その後：

# save the output as main.tf
terraform init   # or: tofu init
export TF_VAR_proxmox_api_token='user@realm!tokenid=uuid'
terraform plan   # import blocks adopt the existing guests

ジェネレーターでマッピングできないオプションは、各リソースブロック内のコメントに記載されます。LXC リソースには ignore_changes = [operating_system] のライフサイクルブロックが含まれます。Proxmox はソーステンプレートを記録しないため、プレースホルダーの template_file_id によって、取り込んだコンテナが置き換えられるのを防ぎます。

リソースとプロンプト

ツールに加え、このサーバーは、参照可能な読み取り専用のクラスター状態を JSON として提供する MCP リソース（proxmox://nodes、proxmox://vms、proxmox://storage）と、一般的なワークフロー用の MCP プロンプト（provision_lxc、health_check、diagnose_permissions）を公開します。

構造化出力

すべてのツールは、人間向けの Markdown の概要と、プログラムで利用するための structuredContent オブジェクトを返します。たとえば、proxmox_get_vms は { count, vms: [{ vmid, name, type, node, status, cpu, mem, maxmem, ... }] } を返します。structuredContent を理解しないクライアントは、テキストをそのまま表示します。

テスト

# Unit tests (no Proxmox server needed)
npm test

# Live read-only integration test (needs a configured Proxmox connection)
node test-basic-tools.js

# Live workflow tests — CREATES AND DELETES real resources; needs elevated mode
node test-workflows.js [--dry-run] [--interactive] [--workflow=lxc|disk|snapshot]

ワークフローテストの詳細については、TEST-WORKFLOWS.md を参照してください。

開発

npm install
npm start        # run the server
npm run dev      # run with auto-reload
npm test         # unit tests

# Poke the server directly over stdio
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js

継続的インテグレーションでは、GitHub Actions（.github/workflows/ci.yml）を介して Node 20 および 22 で npm test を実行します。

既知の制限事項

• TLS 検証はデフォルトで無効になっているため、Proxmox の自己署名証明書でもそのままサーバーを利用できます。CA 署名証明書がある場合は、PROXMOX_VERIFY_TLS=true を設定してください。検証を無効にした状態で、信頼できないネットワーク上のサーバーを指定しないでください。
• proxmox_execute_vm_command、proxmox_get_guest_ips、proxmox_set_cloudinit は QEMU VM のみで動作します。Proxmox HTTP API には LXC コンテナ用の exec／agent エンドポイントがないため、type: lxc ではコマンド実行時に明確な「未対応」メッセージが返されます。代わりに SSH またはホスト上の pct exec を使用してください。

トラブルシューティング

• 「Could not load .env file」という警告 — MCP クライアントの env ブロックを介して変数を渡している場合は無視できます。それ以外の場合は、リポジトリの親ディレクトリに .env を置いてください（mcp-proxmox 内から ls ../.env を実行）。
• 接続拒否／タイムアウト — PROXMOX_HOST、PROXMOX_PORT（デフォルトは 8006）、およびファイアウォールのルールを確認してください。
• 401 Unauthorized — PROXMOX_USER の形式（root@pam）、PROXMOX_TOKEN_NAME、および PROXMOX_TOKEN_VALUE のシークレットが完全であることを確認してください。
• 「Requires Elevated Permissions」 — PROXMOX_ALLOW_ELEVATED=true を設定し、トークンに上記のロールを付与してください。
• QEMU コマンドの実行に失敗する — VM 内に QEMU ゲストエージェントをインストールして有効化し（apt install qemu-guest-agent）、VM のオプションでも有効化してから、VM を再起動してください。

ライセンス

MIT — LICENSE を参照してください。