Proxmox Ops

proxmox-ops-mcp

面向 Proxmox VE 的 MCP 服务，专为运维工作打造：查明集群出了什么问题、备份是否确实存在，以及节点能否停机维护。服务支持写入，但默认关闭，且每次变更都需要显式发起第二次调用。

为什么还要再做一个 Proxmox MCP 服务

现有的服务大多只是逐个暴露 API 端点。对于“启动 VM 104”这样的操作，这没问题；但像*“哪些来宾没有昨晚的备份？”*这样的问题，就需要调用十几个接口，而且模型必须足够了解 Proxmox，才能正确地组合这些信息。它通常做不到。例如，它不会知道缺少 VM.Backup 权限的令牌会得到空的备份列表，而不是错误。

本服务将这些知识融入工具中。backup_audit 会读取备份卷，应用与 vzdump 作业相同的来宾筛选条件，并检查令牌是否有权查看这些卷。模型会收到一份问题列表，其中每项都包含稳定的代码和建议。

状态

0.1 版，可用但尚不成熟。已在以下环境中测试：

Proxmox VE 9.2，单节点，ZFS，两个备份存储	所有读取工具、所有写入工具（在专用池中的临时 VM 上）
多节点集群、HA、Ceph	仅使用真实场景的负载进行了单元测试和集成测试
Proxmox VE 8、Proxmox Backup Server 存储	尚未进行实时测试；欢迎反馈

实时测试发现了 API 文档中未提及的三个问题，本服务都已妥善处理：

• PVE 9 在节点状态调用中将 cpu 和 wait 报告为 0。
• 当令牌缺少权限时，备份列表会返回空结果，而不会报错。
• /cluster/resources 中的信息会比来宾的实际状态延迟几秒。

安装

uvx proxmox-ops-mcp --version          # run without installing (uv)
pipx install proxmox-ops-mcp           # or as a CLI tool
docker pull ghcr.io/derdennis1012/proxmox-ops-mcp

需要 Python 3.11 或更高版本。通过源代码安装：git clone … && uv sync && uv run proxmox-ops-mcp。

设置

**1. 创建 API 令牌。**先从只读权限开始：

pveum user add mcp@pve
pveum acl modify / --users mcp@pve --roles PVEAuditor
pveum user token add mcp@pve ops --privsep 1          # prints the secret once
pveum acl modify / --tokens 'mcp@pve!ops' --roles PVEAuditor

只有此角色时，backup_audit 无法查看备份。更高权限级别需要更多权限，且 Proxmox 的 ACL 规则中有一些容易踩的坑。这两方面都在 docs/proxmox-setup.md 中介绍。

2. 检查连接。

$ export PROXMOX_HOST=pve1.example.com PROXMOX_TOKEN_ID='mcp@pve!ops' PROXMOX_TOKEN_SECRET=…
$ uvx proxmox-ops-mcp check
OK    connected to pve1.example.com:8006 as mcp@pve!ops
      Proxmox VE 9.2.5 (release 9.2)
      3 node(s) visible, access tier: read_only

如果出现 SSLError，节点证书可能未涵盖你使用的地址。通过 VPN 连接时，这种情况很常见。check 会打印用于固定证书的命令。

**3. 将其添加到客户端。**Claude Code：

claude mcp add proxmox-ops \
  -e PROXMOX_HOST=pve1.example.com \
  -e PROXMOX_TOKEN_ID='mcp@pve!ops' \
  -e PROXMOX_TOKEN_SECRET=… \
  -- uvx proxmox-ops-mcp

Claude Desktop、Cursor、VS Code、OpenAI Codex、Gemini CLI、Hermes Agent、OpenClaw 和 Docker：请参阅 docs/clients.md。其中还介绍了自主 Agent 使用本服务时需要注意的事项。

工具

工具	层级
cluster_health	read_only	仲裁、离线节点、CPU/内存、存储使用率、HA 错误
ceph_health	read_only	Ceph 健康检查及提示、OSD 和 PG 状态、监视器仲裁、容量
compare_nodes	read_only	节点间的 I/O 等待、负载、交换空间、内存/I/O 压力（PSI）、版本差异
backup_audit	read_only	缺失、过期和未安排的备份；失败的任务；PBS 验证
recent_task_failures	read_only	指定时间范围内失败的任务
storage_health	read_only	ZFS 池状态、设备和数据错误、清理间隔、SMART、SSD 磨损
node_maintenance_status	read_only	待安装的 Proxmox 更新、需要重启的节点、即将过期的节点证书
recommend_placement	read_only	新来宾适合放置在哪个节点，并提供评分和每个节点的原因
plan_node_evacuation	read_only	节点能否清空、阻碍因素，以及执行所需的命令
list_nodes、list_guests、get_guest、get_task_status	read_only	清单、来宾配置（已隐藏机密）、任务日志
guest_power	operator	启动、关机、重启；stop 需要 admin 权限
create_snapshot	operator	在进行高风险更改前创建快照
migrate_guest	admin	VM 实时迁移，容器重启迁移

参数和所有发现代码见：docs/tools.md。

示例：plan_node_evacuation(node="pve1")，精简版：

{
  "feasible": true,
  "summary": "pve1 can be drained: 3 guests to 2 target nodes, 1 container(s) with a brief restart.",
  "guests": [
    { "vmid": 100, "name": "db01",  "mode": "ha-managed",            "target": "pve3" },
    { "vmid": 101, "name": "web01", "mode": "live-with-local-disks", "target": "pve2",
      "warnings": ["local disks will be copied: scsi0@local-lvm"] },
    { "vmid": 200, "name": "dns01", "mode": "restart",               "target": "pve3" }
  ],
  "steps": [
    "ceph osd set noout   # prevent rebalancing while the node is down",
    "ha-manager crm-command node-maintenance enable pve1   # HA moves its guests automatically",
    "qm migrate 101 pve2 --online --with-local-disks",
    "pct migrate 200 pve3 --restart",
    "# perform maintenance on pve1, reboot, verify it rejoined the cluster",
    "ha-manager crm-command node-maintenance disable pve1",
    "ceph osd unset noout"
  ]
}

写入权限

除非更改 PROXMOX_ACCESS_TIER，否则其值为 read_only，且不会注册高于该层级的工具。写入工具分两步执行：

1. 正常调用时，它会根据实时来宾状态检查请求，并返回操作预览和确认令牌。
2. 使用相同参数和该令牌再次调用时，它才会执行操作。

令牌只能使用一次，有效期为五分钟，并且绑定到确切的参数。这包括节点，因此，如果来宾在此期间迁移，令牌就会失效。还可以将写入操作限制在指定的池或 VMID，并设置每小时的操作上限。每次预览、执行和拒绝都会写入审计日志。

令牌可确保实际执行的内容与预览一致。但它不能证明有人批准了操作，因为模型也能看到令牌。请在 MCP 客户端中为写入工具开启工具审批。没有任何工具可以删除内容。

详情（包括 HTTP 传输默认设置）请见 docs/security-model.md。

配置

带有 PROXMOX_ 前缀的环境变量中，必须设置 HOST、TOKEN_ID 和 TOKEN_SECRET。可选变量包括 ACCESS_TIER、CA_BUNDLE 或 TLS_FINGERPRINT、AUDIT_LOG，以及其他几个变量。只有通过 --env-file 指定时才会读取 .env 文件。完整列表见 docs/configuration.md。

开发

make install   # uv sync + pre-commit
make check     # ruff, mypy --strict, pytest

src/proxmox_ops_mcp/analysis/ 中的诊断逻辑是针对 API 负载执行的纯函数，无需集群即可测试。若要对真实集群运行只读检查，请将 tests/live/ 指向一个环境文件。docs/architecture.md 介绍了项目结构，CONTRIBUTING.md 说明了如何参与贡献。

文档站点：https://derdennis1012.github.io/proxmox-ops-mcp/。计划中的后续功能：直接检查 Proxmox Backup Server（垃圾回收、清理和验证任务）、复制任务、来宾快照维护。

许可证

MIT。Proxmox 是 Proxmox Server Solutions GmbH 的商标；本项目与其无关。