Proxmox MCP

Proxmox + AI - 适用于 ChatGPT、Claude、GitHub Copilot、Microsoft 365 Copilot、Gemini，以及任何支持 MCP 的 Agent

非官方。由社区构建的 Claude Code Skill 和 Proxmox API MCP 服务。与 Proxmox Server Solutions GmbH 无关联，也未获得其认可或赞助。

_{▶ 观看 30 秒演示 - 演示数据为模拟数据；展示的每条命令都存在于实际 CLI 中。}

同样来自 Servosity。 备份与灾难恢复是 Servosity 自有的领域——第一方 Servosity connector 将同样的全机群本地镜像方案（机群关注、过期备份、还原、QBR 报告）带到 Servosity Backup and DR。

只读 Proxmox VE 和 Backup Server CLI，可让你查看所有客户端集群中哪些来宾系统拥有良好、已验证且近期的还原点，哪些没有。可与您正在使用的 AI 配合使用——ChatGPT（Plus/Pro+）、Claude Desktop、Codex、Claude Code、Claude Cowork 和 GitHub Copilot——也可通过远程方式使用 Microsoft 365 Copilot / Copilot Studio 和 Google Gemini。免费、开源，可在笔记本电脑上运行。专为 MSP 所有者打造。无需编写代码。

适用于你的 Agent

MSP 所有者实际使用的六种 Agent（可自行安装，现已可用）：

你的 AI Agent	Proxmox skill 的安装方式
Claude Desktop	运行安装程序，然后通过 Settings > Extensions 注册 proxmox-mcp（无需编辑 JSON）。
ChatGPT（付费方案）	运行安装程序，通过 HTTPS 暴露 proxmox-mcp，并将其注册为 Developer Mode connector。
Codex CLI	粘贴下面的安装提示词。
Claude Code	粘贴下面的安装提示词。
Claude Cowork	粘贴下面的安装提示词。
GitHub Copilot（VS Code）	运行安装程序，在 mcp.json 的 servers 键下添加 proxmox-mcp，然后选择 Agent 模式。

对于 ChatGPT，设置 PROXMOX_MCP_HTTP_TOKEN，运行 proxmox-mcp --transport http，并将其置于 HTTPS 后面暴露——无需桥接包。请参阅 mcp-install.md。

也适用于 Microsoft 和 Google 生态

这两个平台的安装基础庞大，但需要坦诚说明：它们采用的是远程 / 企业方案，而不是你刚安装的本地二进制程序。

Agent	所需条件
Microsoft 365 Copilot / Copilot Studio	无法自行安装。 通过 HTTPS 托管 proxmox-mcp，然后将其接入 Copilot Studio（Tools > Add a tool > Model Context Protocol > Server URL）或声明式 Agent。需要 Copilot Studio 许可证和租户管理员权限。请参阅 mcp-install.md。
Google Gemini	Gemini CLI 在本地运行——与 Claude Code 相同。Gemini app 在远程运行——使用与 ChatGPT 相同的 HTTPS 方案。请参阅 mcp-install.md。

原生支持 Skill 的 Agent（同样适用）： Hermes 和 OpenClaw 可直接读取此 skill 的 SKILL.md，也支持 MCP——请参阅下方的安装章节。还可通过 MCP 与 Cursor、Windsurf、Cline、Continue.dev 和 Zed 配合使用。各工具的完整接入方法：docs/which-agent.md。

要使用多个 Agent？ 运行一条命令，即可为所有 51 种以上受支持的 Agent 完成安装：npx skills add Servosity/msp-skills@latest（需要 Node.js，然后为 CLI/MCP 二进制程序运行各 skill 的安装程序）。请参阅 docs/which-agent.md。

60 秒内完成安装

对 Claude Desktop 来说最快的方法——一键安装 .mcpb

下载 Proxmox MCP（.mcpb），然后打开 Claude Desktop > Settings > Extensions 并选择该文件。一键完成，无需 JSON，也无需 shell。（在发布页面浏览所有 Proxmox 版本。）

更喜欢 Claude Code 插件？添加一次市场后即可安装——立即生效，无需列出目录：

/plugin marketplace add Servosity/msp-skills
/plugin install proxmox@msp-skills

路径 A——向 AI Agent 粘贴一条提示词（推荐）

将以下内容复制到 Claude Code、Codex CLI 或 Claude Cowork 中：

在此 Agent 工作区中安装 Servosity/msp-skills 的 Proxmox Skill 和 MCP 服务。如果此工作区使用 POSIX shell（macOS、Linux、WSL 或 Bash），运行 bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/proxmox/install.sh)。如果使用 Windows PowerShell，运行 iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/proxmox/install.ps1 | iex。然后按照 README 进行身份验证，并运行 proxmox-cli --help 了解用法。

同一条提示词适用于任何能够运行 shell 的 Agent。

路径 B——自行运行安装程序

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/proxmox/install.ps1 | iex

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/proxmox/install.sh)

安装程序会将 proxmox-cli（CLI）和 proxmox-mcp（MCP 服务）都安装到用户的 bin 路径。Claude Code、Codex 和 Cowork 会通过此目录中的 SKILL.md 发现 Skill。

验证：

proxmox-cli --version

升级到最新版本

安装程序始终获取当前版本——重新运行即可升级：

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/proxmox/install.sh)

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/proxmox/install.ps1 | iex

Claude Desktop .mcpb 用户：下载最新的 .mcpb（见本节顶部），然后在 Settings > Extensions 中重新选择。Claude Code 插件用户：/plugin update proxmox@msp-skills。

添加到 Claude Desktop、GitHub Copilot、Gemini CLI、Microsoft 365 Copilot 或其他 MCP 客户端

安装程序运行后，请查看 mcp-install.md 和 docs/which-agent.md，了解各 Agent 的接入方式——每个 Agent 都有单独的说明，其中包括 GitHub Copilot 的 servers 键，以及远程 Microsoft 365 Copilot / Copilot Studio 接入方式。Claude Desktop 的 Settings > Extensions 面板是最简单的方式；面向偏好编辑 JSON 的用户，mcp-install.md 中也提供了 MCP 配置块。

为 Hermes 安装

在 Hermes CLI 中：

hermes skills install servosity/msp-skills/skills/proxmox --force

在 Hermes 聊天会话中：

/skills install servosity/msp-skills/skills/proxmox --force

Hermes 原生支持 MCP，因此也可以直接使用 proxmox-mcp 服务——安装方式和环境变量相同。

为 OpenClaw 安装

告诉你的 OpenClaw Agent（复制以下内容）：

从 https://github.com/servosity/msp-skills/tree/main/skills/proxmox 安装 proxmox skill。该 skill 定义了如何通过 openclaw: frontmatter 块安装其必需的 CLI（proxmox-cli）。

OpenClaw 尚未普遍开放使用；frontmatter 接入配置已预先提供，OpenClaw 一经发布即可启用。

身份验证

为每个产品创建一个权限隔离的 API 令牌：PBS 在 / 上分配 Audit 角色；PVE 在 / 上分配 PVEAuditor，如果备份存储在 PVE 存储上，还需分配 Datastore.AllocateSpace 和 VM.Backup（参见需要什么 API 令牌？）。然后：

export PROXMOX_HOST=pve1.example.lan
export PROXMOX_API_TOKEN='monitor@pve!agent=<secret>'      # USER@REALM!TOKENID=SECRET
export PROXMOX_TLS_FINGERPRINT='<PVE certificate SHA-256>'  # stock Proxmox certificates are self-signed
# Optional, for PBS verify, datastore and sync data:
export PROXMOX_PBS_HOST=pbs.example.lan
export PROXMOX_PBS_API_TOKEN='monitor@pbs!agent:<secret>'  # colon before the secret
export PROXMOX_PBS_TLS_FINGERPRINT='<PBS certificate SHA-256>'
proxmox-cli doctor

需要管理多个客户端？为每个客户端集群添加一条记录即可；clusters.toml 只存储各令牌对应的环境变量名称：

proxmox-cli clusters add acme --client "Acme Dental" --pve-host pve1.acme.lan --pve-token-env ACME_PVE_TOKEN --pve-fingerprint '<sha256>' --pbs-host pbs.acme.lan --pbs-token-env ACME_PBS_TOKEN --pbs-fingerprint '<sha256>'
proxmox-cli clusters list

doctor 会检查配置、路径、API 可达性，以及 PVE 令牌是否通过身份验证。运行 proxmox-cli posture --agent，确认该令牌还能查看虚拟机、作业和备份：无法读取的内容会列在 fetch_failures 下。

此技能的功能

MSP 经常提出的问题	命令
哪些客户 VM 缺少可靠的近期备份（已验证，并显示其在 PBS 上的位置）？	proxmox-cli posture --only problems --agent
哪些 VM 或磁盘未纳入任何已启用的备份作业？	proxmox-cli backup coverage --include-disks --agent
昨夜哪些任务失败或中途停止？按客户机列出，并附上错误行。	proxmox-cli failures --since 24h --agent
PBS 验证失败已经波及多大范围？	proxmox-cli verify-health --agent
哪些备份数据存储将在 30 天内用满？	proxmox-cli capacity --within 30d --agent
VM 104 有哪些经 PBS 验证的还原点？	proxmox-cli restore-points "104" --verified-only --agent
按客户统计，本月每次计划的备份都生成了还原点吗？	proxmox-cli rpo --days 30 --by-client --csv

完整命令参考：guide.md。有关 AI Agent 操作规范（--agent、--dry-run，以及何时应在执行变更前确认），请参阅 AGENTS.md。

有何不同

大多数 Proxmox MCP 服务都是为管理单个集群而构建的：列出 VM、启动和停止 VM、创建快照，并用标志控制危险操作。许多 MSP 绝不会把这种令牌交给 AI Agent。此工具对 Proxmox 只执行读取操作（HTTP GET），因此没有可能误触发的写入命令；如果备份使用 Proxmox Backup Server，两个令牌也都可以设为仅审计权限。

关键在于关联数据。“这台 VM 有备份吗？”这个问题需要结合 Proxmox 分散在不同位置的四类信息：是否有已启用的作业包含该 VM、任意备份存储上的最新实际归档、Proxmox Backup Server 是否验证过该归档，以及最近一次 vzdump 任务日志中关于该客户机的记录。posture 会对每个客户集群中的所有客户机执行这种关联（backup coverage 则回答第一部分：哪些客户机和磁盘未被任何已启用的作业包含）；failures 和 rpo 会涵盖作业涉及的所有客户机，并且每次运行时都会读取实时数据。对于清单查询，sync 会维护一个本地 SQLite 镜像，支持全文搜索。

解决的痛点

拥有众多客户的 Proxmox 服务商会为每个客户运行一个集群，通常还会运行一台 Backup Server。备份任务显示成功，并不意味着每台客户机都已备份：一个 vzdump 作业会备份多台客户机，而失败的那台只会在任务日志中注明。验证失败也会悄然扩散。在一个 Proxmox 论坛帖子中，一家通过中央 PBS 为 100 到 200 台服务器备份的服务商发现，每周的验证作业报告中失败快照数量不断增加，直到后来才查明原因。另一次，当有人在同一论坛上分享 Proxmox 的 AI Agent 管理层时，管理员强烈反对让 Agent 接触他们的主机。

此技能无需用户给予这种信任，就能回答早间常见问题：

• posture --only problems - 列出所有未纳入备份、没有还原点、备份过期、验证失败或最近一次尝试失败的客户机
• backup coverage --include-disks - 列出未被任何已启用作业包含的所有客户机或磁盘，并说明原因
• failures --since 24h - 列出失败和未明确报错但未完成的任务，每个客户机或数据存储占一行，并附上错误行
• verify-health - 显示验证失败的波及范围，以及剩余的最新验证通过还原点
• rpo --days 30 --by-client - 按客户提供证明，确认每次计划运行都生成了还原点

更详细的说明请参阅 pain-point.md。

常见问题

这能与 ChatGPT 配合使用吗？

可以，适用于 Plus、Pro、Team、Business、Enterprise 和 Education 计划（Free 版目前尚未开放 Developer Mode）。ChatGPT 通过 HTTPS 连接远程 MCP 服务，而不是本地 stdio 二进制程序。Proxmox MCP 服务在本地运行，但原生支持 HTTP：将 PROXMOX_MCP_HTTP_TOKEN 设置为一个足够长的随机值，使用 proxmox-mcp --transport http 启动（默认提供 http://127.0.0.1:7777/mcp，且未设置该令牌时会拒绝启动），并将该端点放在 HTTPS 隧道或你自己的反向代理之后。无需使用桥接包。请参阅 mcp-install.md 中的分步说明。

这能与 Codex、Cursor、Windsurf、Cline、Copilot 或 Gemini 配合使用吗？

可以——它们都支持 MCP。上方矩阵中列出了跨工具安装命令，深入说明请参阅 docs/which-agent.md。

我需要懂编程吗？

不需要。推荐的安装方式是向 Claude Code 或 Codex 粘贴一句话——你的 Agent 会读取 SKILL.md 并完成安装。备用方式是每种操作系统对应的一行安装命令（bash 或 PowerShell）。这两种方式都不需要编写代码。你只需输入一次 Proxmox 凭据。

我的 Proxmox 数据安全吗？

你的数据会保留在自己的计算机上。CLI 和 MCP 服务都是本地二进制程序。SQLite 镜像存放在你用户帐户目录下的一个目录中。AI Agent 只能看到 CLI 返回的内容——通常是查询结果，而不是原始批量数据。凭据从你的环境或 Agent 配置中读取；MSP Skills 绝不会将其打包进此代码库或传输到任何地方。

AI 能停止、更改或删除 Proxmox 主机上的内容吗？

不能。CLI 和 MCP 服务仅包含对 Proxmox VE 和 Proxmox Backup Server 的读取（GET）调用；没有任何命令会启动、停止、迁移、还原、清理或删除任何内容。唯一的写入操作针对本地文件：集群列表、已保存的令牌、本地镜像（每个端点的读取命令也会更新该镜像，保留返回的内容，包括注释）以及 Agent 学习存储。没有响应缓存。Posture、backup coverage、verify-health、failures、capacity、restore-points 和 rpo 始终实时读取 Proxmox；如果无法连接 Proxmox，针对单个端点的读取命令才会从本地镜像返回结果，并在 stderr 和 meta.source: local 中说明这一点；使用 --data-source live 时则会拒绝返回结果。像第三方存储插件密码这样的敏感字段会在缓存、存储或显示之前进行脱敏，并且每个 --cluster 都使用各自的本地存储。需要了解的一项副作用是：读取存储状态时，Proxmox 会挂载已启用的存储；Proxmox 自己的状态守护进程本来就每 10 秒执行一次此操作。

它需要什么 API 令牌？

每个产品都需要一个权限分离的 API 令牌。Proxmox Backup Server：在 / 上授予 Audit 角色（只读）。Proxmox VE：在 / 上授予 PVEAuditor 角色。有一点需要注意：Proxmox VE 只有在令牌同时拥有 Datastore.AllocateSpace 和 VM.Backup 权限时，才会列出备份文件。因此，如果备份存放在 dir、NFS 或 CIFS 存储上，或者尚未在此处配置 Backup Server，请添加一个包含这两项权限的自定义角色。仅有审计权限的令牌会被报告为“存储未读取”，来宾会被标记为 unproven，绝不会报告为“无备份”。如果备份存放在 Proxmox Backup Server 上，且已设置 PROXMOX_PBS_HOST（拼写应与 PVE 存储的 server 字段一致：使用相同的 IP 或主机名），CLI 会通过 PBS API 读取备份，PVE 令牌可以保持仅审计权限。若未设置，PBS 存储只能通过 Proxmox VE 读取；Proxmox VE 会使用该存储中保存的 PBS 凭据列出内容，因此可能会漏掉由其他凭据拥有的备份组：其还原点会计入，但没有还原点的来宾会被报告为未验证，而不是从未备份；该集群中任何由备份作业覆盖的来宾都不会显示为绿色（新建的来宾会标记为 archives-incomplete，因为较新的备份可能因验证失败而被隐藏）。在默认安装中，local 存储也接受备份：使用仅审计权限的令牌时，它会列在获取失败项中，除非你从其内容类型中移除“VZDump backup file”，或授予令牌上述两项权限。在此之前，新来宾的判定结果不受影响，但没有可读取还原点或只有较旧还原点的来宾会被报告为未验证，而不是从未备份或已过期（不可读取的存储中可能有备份）；rpo 会将错过的运行计为未验证，而 posture --fail-on-red 会以状态码 1 退出。在 / 上授予角色（并向下传播），且不要在其下方设置 NoAccess 或更窄范围的 ACL：Proxmox 会从所有列表中排除令牌无权查看的来宾和存储；CLI 会标记缺失或范围过窄的授权，但对某个来宾显式设置的 NoAccess 对任何读取操作都不可见。PVE 令牌格式为 USER@REALM!TOKENID=SECRET；PBS 令牌则在密钥前使用冒号。

Proxmox 使用自签名证书。我必须关闭证书检查吗？

不需要，也没有关闭选项。使用 PROXMOX_TLS_FINGERPRINT 和 PROXMOX_PBS_TLS_FINGERPRINT 固定证书的 SHA-256 指纹（可在节点的 Certificates 下查看），也可以在 clusters.toml 中按客户端集群配置。格式错误的指纹会导致错误，绝不会被静默忽略；PVE 指纹也不能验证 PBS 主机。

如何覆盖多个客户端集群？

使用 proxmox-cli clusters add 为每个客户端添加一个条目，其中包含 PVE 主机、可选的 PBS 主机和命名空间、证书指纹，以及用于存放其令牌的环境变量名称（绝不能填写令牌本身）。之后，集群命令会在所有已配置的集群上运行；使用 --cluster 或 --client 可缩小到单个集群。对于 MCP 客户端，也要将这些令牌变量添加到 MCP 服务的 env 块中。在共享的 Backup Server 上，为每个客户端集群分配各自的 PBS 命名空间，并将其声明为该条目的 pbs_namespace（仅为每个客户端单独设置数据存储还不够：只有声明的命名空间才能限定无法读取的集群）。不同集群可能有重复的 VMID，因此，如果两个集群向同一命名空间写入数据，CLI 无法判断快照中的 vm/100 属于哪个集群，会报告重叠情况，并且不会计入这些还原点。无法读取的集群会被视为可能写入其声明的 pbs_namespace 中的任意位置；如果未声明，则视为可能写入其 PBS 上的任意位置（如果该条目未指定 PBS，则视为可能写入任何 PBS）。因此，声明命名空间可避免某个客户端中断导致其他客户端的备份被隐藏。

费用是多少？

免费，采用 Apache-2.0 许可。你只需为使用的 AI Agent（Claude、ChatGPT、Codex 等）付费，费用由你的 AI 提供商收取，而不是我们。

安全模型

此技能向 Proxmox 发送的每个请求都是读取请求，因此各层级关注的是在你的机器上会发生什么，以及输出会发送到哪里。

层级	示例	建议的 Agent 策略
读取（Proxmox）	posture、backup coverage、failures、verify-health、capacity、restore-points、rpo，以及所有 vm、ct、nodes、storage、tasks、cluster 和 pbs-* 命令	允许
本地写入	sync、workflow archive、export、profile save、teach	允许
凭据路由（本地）	clusters add（各客户端的令牌会存放在哪里，以及信任哪个证书）、auth set-token、auth logout	由人工执行；这些都不是 MCP 工具
数据离开机器	任何命令使用 --deliver webhook:<url> 或 --deliver file:<path>，feedback --send，MCP 服务桥接到公共 HTTPS 端点	仅限人工参与
Proxmox 写入（启动、停止、恢复、清理、删除）	无——此技能没有此类命令	此技能无法执行

最有力的控制仍然是你授予令牌的权限范围：如果备份存储在 Proxmox Backup Server 上，两个令牌都可以设置为仅审计权限，因此即使有人发送写入请求，Proxmox 本身也会拒绝。存储在 PVE 上的备份需要两项备份权限，Proxmox VE 才会列出这些备份；其中的权衡在 governance.md 中有说明。完整详情（包括如何锁定权限）请参阅 governance.md。

状态

Beta 版。已使用模拟响应针对 Proxmox VE 和 Proxmox Backup Server API 接口进行验证，目前正在每周 Build Sessions 中，与在自有集群上运行该技能的 MSP 一起进行实际验证。请通过 compoundingteams.com/build-sessions RSVP。

---

标准。 符合开放的 Agent Skills 规范（Anthropic，2025 年 12 月；适用于 40 多种 Agent）。兼容 MCP——可与任何支持 MCP 的 Agent 配合使用，包括 Hermes。适配 OpenClaw（frontmatter 已预先配置，等待 OpenClaw 发布）。

由 Servosity 维护。采用 Apache-2.0 许可证。使用 CLI Printing Press 构建。最后更新：2026-10-14。