drumfire-proxmox-mcp

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

它是一个 Cloudflare Worker，部署方式与现有的 Firefly III MCP 服务器相同：点击按钮，设置几个 secrets，然后将其作为自定义连接器添加到 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. Datacenter → Permissions → Roles → Create
   名称：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 使用的 secret——之前的权衡问题为了简单起见默认使用一个令牌，但这里没有任何内容要求这样做。

2. Datacenter → Permissions → Users → Add 添加一个专用用户，例如 claude-agent@pve（无需密码，它只会通过 API 令牌进行身份验证）。

3. Datacenter → Permissions → Add → 路径 /，用户 claude-agent@pve，角色 ClaudeHomelabOps。

4. Datacenter → Permissions → API Tokens → Add → 用户 claude-agent@pve，令牌 ID 例如 homelab-mcp。保持勾选“Privilege Separation”，并为令牌本身授予相同的 / → ClaudeHomelabOps ACL。复制令牌 ID（claude-agent@pve!homelab-mcp）和 secret（仅显示一次）——下面你两者都需要。

2. 确保计算器 VM 的 guest agent 已启用

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

1. 在 Proxmox 中 VM 的 Options 选项卡中，确认“QEMU Guest Agent”已启用。

2. 在 Windows VM 内部，如果尚未安装 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. 部署后，设置 secrets

无论你使用按钮还是 CLI，都需要三个 secrets，并且它们刻意不存放在此仓库中（它们不在 wrangler.jsonc 中，该文件公开没有问题）：

在 Cloudflare 仪表板的 Worker → Settings → Variables and Secrets → Add → Encrypt 下设置它们，或通过 npx wrangler secret put <NAME> 设置。

还要仔细检查 wrangler.jsonc 中的明文（非 secret）变量 NETWORTH_VM_PATH——它自带一个占位符（C:\Users\CHANGE_ME\Documents\net-worth\data.json），需要第 2 步中的真实 Windows 用户名。在 Cloudflare 仪表板的同一 Variables and Secrets 页面下编辑它（作为明文变量，而不是 secret），或编辑 wrangler.jsonc 并重新部署。

5. 将其作为自定义连接器添加到 Claude

在 Claude 的连接器设置中，添加一个指向以下地址的自定义连接器：

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

此 Worker 在执行任何操作前，都会检查每个请求的 Authorization: Bearer <MCP_BEARER_TOKEN>——没有它，每次工具调用都会返回 401。如果你的 Claude 连接器设置允许附加自定义 header/API key，请在该处设置该 header。如果不允许，则有两个选项：

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

• 作为安全性较低的备选方案，删除 src/index.ts 中的 bearer-token 检查（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 再添加一项权限（通常只需重新确认 Sys.Audit 已应用于 /，而不仅仅是某个子路径）。