Skip to main content
Glama
drumfire-proxmox-mcp

drumfire-proxmox-mcp

by Drumfire01

drumfire-proxmox-mcp

Claudeがチャット経由でDRUMFIRE Proxmoxクラスターを管理できるようにするリモートMCPサーバーです。インベントリ、電源制御、ライブ設定変更、VM/コンテナの作成/クローン、スナップショット、ネットワーク/ファイアウォール/クラスターの可視化、ゲスト内でのコマンド実行、QEMU Guest Agent経由でVMのファイルシステムに直接ファイルをプッシュすることもできます(ここでは、Firefly IIIからの新しいエクスポートでVM 107上で動作するネットワース計算機を更新するために使用)。

これはCloudflare Workerで、既存のFirefly III MCPサーバーと同じ方法でデプロイします。ボタンをクリックし、いくつかのシークレットを設定し、Claudeにカスタムコネクタとして追加するだけです。

意図的に実行しないこと

このサーバーには、VM/コンテナ/ディスク/スナップショットの削除やスナップショットのロールバックツールはありません。「事前に確認する」のではなく、単にコード上に存在しないため、誤ってでもこのサーバー経由でそれらが起こることはありません。

とはいえ、下のセキュリティノートをお読みください。VM/コンテナの作成がスコープに含まれるため、基になるProxmoxトークンは技術的にはそれらを削除することもできます(Proxmoxはこれらの権限を一緒に結び付けています)。ここでの保証は、ソフトウェアによる強制(そのようなツールは存在せず、Claudeは破壊的な操作の前に常に確認するよう指示されています)であり、このサーバーのv1のような資格情報レベルでの強固な壁ではありません。下の「セキュリティモデル」を参照してください。

Related MCP server: Proxmox MCP Server

このサーバーが公開するツール

ツール

機能

list_nodes

クラスターノードとそのステータスを一覧表示

list_vms / list_containers

ノード(または全ノード)上のQEMU VM / LXCコンテナを一覧表示

get_guest_status

1つのVM/コンテナのステータス

start_guest / shutdown_guest / stop_guest / reboot_guest

電源管理(shutdown はグレースフル、stop は強制電源オフ)

guest_agent_ping

VM内のQEMU Guest Agentが稼働しているか確認

write_vm_file

ゲストエージェント経由で任意のVM内の絶対パスにテキストコンテンツを書き込む

update_networth_calculator

write_vm_file の便利なラッパーで、ネットワース計算機VMを特にターゲットにします

get_cluster_status

クラスター/ノードのヘルスとクォーラム

get_node_network

ノードのブリッジ/VLAN/ボンド

get_firewall_rules

データセンター/ノード/ゲストレベルの読み取り専用ファイアウォールルール

get_vm_network_info

VMの実際のライブIP/インターフェース(ゲスト内部から報告)

run_guest_command / get_guest_command_result

ゲストエージェント経由でVM内でコマンドを実行(例: ping, ipconfig)— シェルアクセスと同等。注意点はツール自身の説明を参照

get_next_vmid

次に空いているVM/コンテナID

update_vm_config / update_container_config

CPU/メモリ/ネットワーク/ディスク接続などの設定を変更

resize_vm_disk

ディスクを拡張(ProxmoxはこのAPIでの拡張のみ許可し、縮小は不可)

create_vm / create_container

新しいVM / LXCコンテナを作成

clone_vm

既存のVMまたはテンプレートをクローン

create_snapshot / list_snapshots

スナップショットの作成と一覧表示(ロールバック/削除ツールはなし)

セキュリティモデル

  • 電源/ステータス/設定/作成/クローン/スナップショット作成ツール: このスコープの決め方に従い、事前に確認せずに実行してもよい「自由な操作」として扱われます。ここにあるものは本質的に破壊的ではありません。

  • run_guest_command: ゲスト内で指示された内容を実行します。SSH/RDPアクセスと同等です。診断や日常的な変更には適しています。Claudeは、ゲスト内で破壊的または元に戻せないように見える操作の前に、一時停止してあなたに確認するよう指示されています。

  • このサーバーはVM、コンテナ、ディスク、スナップショットを削除またはロールバックしません。 それが実際の最後の防衛線であり、Proxmoxトークンの権限ではありません。下記のロールを参照してください。このロールは VM.Allocate を許可します(作成に必要であり、Proxmoxは削除にもこれを使用します。権限レベルでこれらを分離する方法はありません)。

1. スコープ付きProxmox APIトークンを作成する

root/adminトークンを使い回さないでください。Proxmox Web UIで:

  1. データセンター → 権限 → ロール → 作成 名前: ClaudeHomelabOps。特権: VM.Audit, VM.Monitor, VM.PowerMgmt, Sys.Audit, VM.Allocate, VM.Clone, VM.Snapshot, VM.Config.CPU, VM.Config.Memory, VM.Config.Disk, VM.Config.Network, VM.Config.Options, VM.Config.HWType, VM.Config.CDROM, VM.Config.Cloudinit。

    意図的に除外しているのは VM.Snapshot.Rollback(ロールバックは現在のディスク状態を破棄するため、本当に破壊的)と VM.Backup/VM.Migrate/VM.Console(このサーバーが行うどの処理にも不要)です。上で述べたように、VM.Allocate は create_vm/create_container/clone_vm に必要であり、Proxmoxもこれをゲストの削除に使用します。より細かい分割はできないため、「削除できない」という保証は、このサーバーに削除ツールが単に存在しないことによるものであり、トークンの権限によるものではありません。

    もし日常的にはより厳格な資格情報レベルの保証を維持し、作成時のみ一時的に許可したい場合は、代わりに2つ目の、より制限されたトークン(同じロールから VM.Allocate/VM.Config.* を除いたもの)を作成し、実際に何かを作成/再設定したいときにこのWorkerが使用するシークレットを切り替えることができます。先ほどのトレードオフの質問では、簡単のために1つのトークンをデフォルトとしましたが、ここでそれを必須とするものはありません。

  2. データセンター → 権限 → ユーザー → 追加 で専用ユーザー(例: claude-agent@pve)を追加します(パスワードは不要です。APIトークン経由でのみ認証されます)。

  3. データセンター → 権限 → 追加 → パス /、ユーザー claude-agent@pve、ロール ClaudeHomelabOps。

  4. データセンター → 権限 → APIトークン → 追加 → ユーザー claude-agent@pve、トークンID 例: homelab-mcp。「特権分離」はチェックしたままにし、同じ / → ClaudeHomelabOps ACLをトークン自体にも付与します。トークンID(claude-agent@pve!homelab-mcp)とシークレット(一度だけ表示)をコピーしてください。両方とも後で必要になります。

2. ネットワース計算機VMのゲストエージェントが有効になっていることを確認する

write_vm_file / update_networth_calculator ツールは、VM 107(VM-OnPremTest)内でQEMU Guest Agentが実行されている必要があります。

  1. ProxmoxのVMのオプションタブで、「QEMU Guest Agent」が有効になっていることを確認します。

  2. Windows VM内に、まだインストールされていなければゲストエージェントサービスをインストールし(virtio-win ISOに qemu-ga-x86_64.msi として同梱)、「QEMU Guest Agent」Windowsサービスが実行中であることを確認します。

  3. アプリのデータフォルダがどのWindowsユーザーアカウントの下にあるかを確認してください。ゲストエージェントサービスはSYSTEMとして実行されるため、ファイル書き込みには相対パスではなく完全な絶対パス(例: C:\Users\<username>\Documents\net-worth\data.json)が必要です。

3. デプロイ

Deploy to Cloudflare

(先にこのリポジトリをGitHubにプッシュし、上記の REPLACE_WITH_THIS_REPO_URL を https://github.com/<you>/<repo> に置き換えてください。GitHubはリポジトリが存在する前にボタンを自身にリンクさせることを許可していません。)

ボタンをクリックすると、リポジトリがCloudflare Workers Buildsにフォーク/接続され、あなたの代わりにデプロイが実行されます。ただし、この時点ではまだ使用できません。手順4を参照してください。

手動デプロイ(ボタンの代替)

npm install
npx wrangler secret put PROXMOX_TOKEN_ID
npx wrangler secret put PROXMOX_TOKEN_SECRET
npx wrangler secret put MCP_BEARER_TOKEN   # any long random string you generate
npx wrangler deploy

4. デプロイ後にシークレットを設定する

ボタンを使ったかCLIを使ったかに関わらず、3つのシークレットが必要です。これらは意図的にこのリポジトリには含まれていません(wrangler.jsonc には含まれておらず、公開しても問題ありません)。

シークレット

値

PROXMOX_TOKEN_ID

claude-agent@pve!homelab-mcp(手順1より)

PROXMOX_TOKEN_SECRET

トークンシークレット(手順1より)

MCP_BEARER_TOKEN

自分で生成する任意の長いランダム文字列(例: openssl rand -hex 32)

CloudflareダッシュボードのWorker → 設定 → 変数とシークレット → 追加 → 暗号化で設定するか、npx wrangler secret put <NAME> で設定します。

また、wrangler.jsonc 内の平文(非シークレット)変数 NETWORTH_VM_PATH も再確認してください。この変数には、手順2の実際のWindowsユーザー名が必要なプレースホルダー(C:\Users\CHANGE_ME\Documents\net-worth\data.json)が入っています。Cloudflareダッシュボードの同じ変数とシークレットページで(シークレットではなく平文変数として)編集するか、wrangler.jsonc を編集して再デプロイしてください。

5. Claudeにカスタムコネクタとして追加する

Claudeのコネクタ設定で、次の場所を指すカスタムコネクタを追加します:

https://<your-worker-subdomain>.workers.dev/mcp

このWorkerは、何かを行う前に、すべてのリクエストに Authorization: Bearer <MCP_BEARER_TOKEN> が含まれているかを確認します。これがないと、すべてのツール呼び出しは401になります。Claudeコネクタの設定でカスタムヘッダー/APIキーを添付できる場合は、そこにそのヘッダーを設定してください。できない場合の2つの選択肢は次のとおりです:

  • 代わりに、Worker のルートの前に Cloudflare Access ポリシーを配置します(推奨 — これは、クライアントがカスタムヘッダーを送信できない場合に個人用 MCP エンドポイントをロックダウンする標準的な方法です)、または

  • より安全性の低い代替策として、src/index.ts(fetch() の関数先頭)内のベアラートークンチェックを削除し、Worker の URL 自体が推測できないことに依存します。Proxmox にアクセスできるものには推奨されません。

6. 試してみる

接続できたら、Claude のチャットで: 「drumfire03 の VM を一覧表示して」 または 「VM 107 のステータスは?」 と入力すれば、実際のデータが返されます。純資産ワークフローの場合、Claude は Firefly III(すでに接続済み)からデータを取得し、計算機が期待する JSON を構築して、その JSON を文字列として update_networth_calculator を呼び出します。

それが機能したら、新しいツールも試してみてください — 「クラスターのヘルスを確認して」、「VM 107 の現在の実際の IP は?」、「VM-OnPremTest をテスト用コピーにクローンして」、「その VM を 4 コアに増やして」。

権限に関する注意: Proxmox のファイアウォールルールおよび一部のネットワーク読み取りエンドポイントの正確な権限要件はバージョンによって多少異なり、上記のロールはベストエフォートの対応付けであり、お使いの特定の Proxmox バージョンでテストされたものではありません。ツール呼び出しが 403 で返ってきた場合、エラーメッセージには Proxmox の実際の応答が含まれます — 修正方法はほぼ常に ClaudeHomelabOps に権限を 1 つ追加することです(通常は Sys.Audit がサブパスのみでなく / に適用されていることを再確認するだけです)。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers