drumfire-proxmox-mcp

一个远程 MCP 服务器，让 Claude 可以通过聊天管理 DRUMFIRE Proxmox 集群——包括清单、电源控制、实时配置更改、创建/克隆虚拟机与容器、快照、网络/防火墙/集群可见性、在客户机内运行命令，以及通过 QEMU Guest Agent 将文件直接推送到虚拟机的文件系统（此处用于用 Firefly III 的新导出更新运行在 VM 107 上的净值计算器）。

它是一个 Cloudflare Worker，部署方式与现有的 Firefly III MCP 服务器相同：点击按钮，设置几个密钥，然后将其作为自定义连接器添加到 Claude。

它刻意不做什么

没有虚拟机/容器/磁盘/快照删除或快照回滚工具——不是“先询问”，而是代码中根本不存在，因此即使误操作也不会通过此服务器发生。

话虽如此，请阅读下面的安全说明：因为创建虚拟机/容器在范围内，底层 Proxmox 令牌技术上也可以删除它们（Proxmox 将这些权限绑定在一起）——这里的保证是软件层面的（不存在此类工具，并且 Claude 被指示在执行任何破坏性操作前总是先询问），而不是像此服务器 v1 那样的硬性凭据级壁垒。请参阅下面的“安全模型”。

Related MCP server: proxmox-mcp

此服务器暴露的工具

安全模型

• 电源/状态/配置/创建/克隆/创建快照工具：按照你的范围界定，这些被视为无需事先询问即可运行的“合理操作”——这里没有任何操作本质上是破坏性的。

• run_guest_command：在客户机内按指令执行任意操作，相当于 SSH/RDP 访问。适用于诊断和日常更改；Claude 被指示在客户机内执行任何看起来具有破坏性或不可逆的操作之前暂停并与你确认。

• 此服务器中的任何工具都不会删除或回滚虚拟机、容器、磁盘或快照。 这才是真正的底线，而不是 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 也用它来删除客户机——没有更细粒度的拆分可用，因此这里的“无法删除”保证仅仅来自此服务器没有删除工具，而不是来自令牌的权限。

   如果你更愿意在日常使用中保留更严格的凭据级保证，并且只临时授予创建权限，你也可以创建一个第二个、更受限的令牌（同一个角色减去 VM.Allocate/VM.Config.*），并在你确实想要创建/重新配置某些内容时切换此 Worker 使用的密钥——之前关于权衡的问题出于简单考虑默认使用一个令牌，但这里没有任何要求必须如此。

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. 确保计算器虚拟机的 guest agent 已启用

write_vm_file / update_networth_calculator 工具需要 VM 107（VM-OnPremTest）内运行 QEMU Guest Agent：

1. 在 Proxmox 中虚拟机的选项选项卡里，确认已启用“QEMU Guest Agent”。

2. 在 Windows 虚拟机内部，如果尚未安装 guest agent 服务，请安装它（该服务随 virtio-win ISO 一同提供，文件名为 qemu-ga-x86_64.msi），并确保“QEMU Guest Agent”Windows 服务正在运行。

3. 注意应用的数据文件夹位于哪个 Windows 用户帐户下——guest agent 服务以 SYSTEM 身份运行，因此文件写入需要完整的绝对路径，例如 C:\Users\<username>\Documents\net-worth\data.json，而不是相对路径。

3. 部署

（先将此仓库推送到 GitHub，然后把上面的 REPLACE_WITH_THIS_REPO_URL 替换为 https://github.com/<you>/<repo>——在仓库存在之前，GitHub 不允许按钮链接到自身。）

点击按钮会将仓库 fork/连接到 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，都需要三个密钥，它们刻意不包含在此仓库中（它们不在 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 密钥，请在那里设置该标头。如果不允许，有两个选项：

• 改为在 Worker 路由前加一个 Cloudflare Access 策略（推荐做法——当客户端无法发送自定义标头时，这是锁定个人 MCP 端点的标准 方式），或者

• 作为安全性较低的备选方案，删除 src/index.ts 中的 bearer-token 检查 （fetch()，函数顶部），并依靠 Worker 的 URL 本身难以被猜中。不建议用于 任何可能涉及 Proxmox 的场景。

6. 试一试

连接后，在 Claude 聊天中："列出 drumfire03 上的虚拟机" 或 "VM 107 的状态如何" 应返回真实数据。对于净资产工作流，Claude 从 Firefly III（已连接） 拉取数据，构建计算器所期望的 JSON，并以字符串形式将该 JSON 传给 update_networth_calculator。

这些都能正常工作后，再试试较新的工具——"检查集群的健康状态"、 "VM 107 现在的实际 IP 是什么"、"把 VM-OnPremTest 克隆为一份测试副本"、 "把那台 VM 提升到 4 核"。

关于权限的说明： Proxmox 对防火墙规则和某些网络读取端点的确切权限要求 会因版本而略有差异，上述角色是尽力而为的映射，并未针对你的特定 Proxmox 版本 测试过。如果某个工具调用返回 403，错误信息会包含 Proxmox 的实际响应—— 解决办法几乎总是给 ClaudeHomelabOps 再添加一条权限（通常只需重新确认 Sys.Audit 已应用在 / 上，而不仅仅是某个子路径）。