drumfire-proxmox-mcp

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

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

これが意図的にやらないこと

VM/コンテナ/ディスク/スナップショットの削除やスナップショットのロールバックツールはありません。「事前に確認する」のではなく、単にコード内に存在しません。したがって、このサーバーを介して誤って実行されることはあり得ません。

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

Related MCP server: ProxmoxEmCP

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

セキュリティモデル

• 電源/ステータス/設定/作成/クローン/スナップショット作成ツール: このスコープの指定どおり、事前に確認せずに実行してよいものとみなされます。ここにあるものは本質的に破壊的ではありません。

• 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として同梱されています）、Windowsサービス「QEMU Guest Agent」が実行中であることを確認します。

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

3. デプロイ

(まずこのリポジトリを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にもありません。これは公開しても問題ありません）。

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

また、wrangler.jsonc内の平文（非シークレット）変数NETWORTH_VM_PATHも再確認してください。初期状態ではプレースホルダー（C:\Users\CHANGE_ME\Documents\net-worth\data.json）が入っており、手順2の実際のWindowsユーザー名に置き換える必要があります。これは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 がサブパスだけでなく / に適用されていることを再確認するだけです）。