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

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

セキュリティモデル

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

• 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. デプロイ

（先にこのリポジトリを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 も再確認してください。この変数には、手順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 がサブパスのみでなく / に適用されていることを再確認するだけです）。