Proxmox VE (Mojood Connect)

Proxmox VE MCP 服务

用日常语言询问 Claude 关于你的 Proxmox VE：哪些虚拟机没有备份作业覆盖，哪些虚拟机的备份已逾期，哪些生产虚拟机已停止运行，以及某台虚拟机的情况如何。你也可以在同一聊天中启动、关闭或重启虚拟机，并创建快照；任何更改执行前都会经过确认。没有任何工具可以删除虚拟机、还原备份或回滚快照。

由 Mojood Connect 构建，作为 Proxmox 的可运行演示。它通过 REST API 和 API token 连接任意 Proxmox VE 8 或 9。本仓库包含一个脚本，可在 Apple Silicon Mac 上的虚拟机中安装本地 Proxmox VE 9.2（Proxmox 官方 arm64 版本），并配置一家虚构公司 Harbor Trading 的示例虚拟机，让你无需接触真实集群即可试用。

工具

工具	功能	是否会进行更改？
overview	节点（CPU、内存、运行时间）、存储使用情况、运行中和已停止的虚拟机、备份作业	否
find_guests	按名称、ID、标签或状态查找虚拟机和容器，并显示 CPU 和内存使用情况	否
guest_details	单个虚拟机：核心数、磁盘、备注、快照、上次备份、是否有备份作业覆盖、近期任务（谁做了什么）	否
needs_attention	未纳入任何备份作业的虚拟机、备份逾期的虚拟机、已停止的生产虚拟机、旧快照、存储空间不足、内存不足的虚拟机	否
power_guest	启动、正常关闭或重启虚拟机或容器	是，需确认
snapshot_guest	创建快照，并附上说明，注明是谁提出的请求	是，需确认

如何确保更改安全。 调用 power_guest 或 snapshot_guest 时，如果没有提供 confirmation，不会进行任何更改：工具会返回一段简明说明（“启动 mail-relay（lima-pve 上的 VM 104，当前已停止）。它带有 prod 标签。”）和一个一次性代码。只有在 10 分钟内，使用该代码再次提交相同请求，更改才会执行。每个代码只能使用一次，且仅适用于签发该代码的请求。服务的指令会要求模型展示说明并等待用户确认。Proxmox 自身的任务日志会记录每项更改，并注明 token 所属用户。

最小权限。 演示使用专属的 Proxmox 用户 claude@pve 及自定义角色，该角色仅包含 VM.Audit、VM.PowerMgmt、VM.Snapshot、Datastore.Audit 和 Sys.Audit 权限，另有 VM.Backup 和 Datastore.AllocateSpace 权限（仅限备份存储），因为 Proxmox 只会向有权备份虚拟机的用户列出该虚拟机的备份。没有任何工具会创建、还原或删除备份。

本地试用

需要一台搭载 Apple Silicon 的 Mac（M3 或更新机型，支持嵌套虚拟化），并安装 Lima、uv 和 Python 3.13，约 6 GB 可用内存和 40 GB 磁盘空间。

scripts/reset.sh                         # Proxmox VE 9.2 in a Lima VM (first run installs it), filled with SAMPLE guests
uv run --env-file .env proxmox-mcp       # MCP server on http://127.0.0.1:8008/mcp (Streamable HTTP)

scripts/up.sh 会按照 Proxmox 的 Debian 13 指南安装 Proxmox VE，添加一个 ZFS 池 （位于文件中），以便对虚拟机和容器创建快照；创建 claude@pve 用户及其令牌，以及一个用于 Web 界面的只读 viewer@pve 用户，Web 界面地址为 https://127.0.0.1:8006。密钥只会写入被 git 忽略的 .env 文件，绝不会 打印出来。本地证书为自签名证书，因此 .env 中设置了 PVE_VERIFY_TLS=0；在真实安装环境中请启用该选项。

Claude Desktop： 将以下内容添加到 claude_desktop_config.json（Settings › Developer），并填写此文件夹的路径：

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "--env-file", "/path/to/proxmox-mcp/.env", "proxmox-mcp", "--stdio"]
    }
  }
}

然后提问：“哪些服务器没有备份？”“erp-app 出了什么问题？”“在今晚更新之前为 erp-app 创建快照，并重新启动 mail-relay。”

你自己的 Proxmox VE： 创建具有上述权限的用户和 API 令牌 （pveum user token add <user> <name> --privsep 0），然后设置 PVE_URL、PVE_TOKEN_ID（user@realm!name）、 PVE_TOKEN_SECRET 和 PVE_SAMPLE=0。

SAMPLE 虚拟机和容器

为 Harbor Trading 配置了六台虚拟机（实际启动运行的 Alpine Linux）和四个 LXC 容器：ERP 数据库和应用服务器、文件服务器、一台被停止的邮件中继服务器、一套已退役且有 96 天前快照的 CRM、一台预发布 Web 服务器、两个 Web 容器、监控系统和 VPN 网关。夜间备份作业覆盖了其中大多数，但并非全部；其中一个虚拟机或容器的最新备份已有 9.9 天。备份和快照都是真实的；scripts/seed.sh 会将其中一些的时间戳回拨，以便展现这批系统的历史记录。这里的一切都是虚构的。

测试

uv run --env-file .env pytest            # unit tests (a fake Proxmox API), plus live tests when the local Proxmox runs

生产版本的新增功能

此演示使用一个 API 令牌。面向 Proxmox 客户的生产版服务将支持每个人使用自己的 Proxmox 账户登录（通过其 realm、LDAP 或 OpenID），这样 Claude 看到和执行的内容就会严格遵循其角色权限；还将支持包含多个节点的集群、Proxmox Backup Server、记录每次工具调用的托管审计日志，以及目录列表。这正是 Mojood Connect 所构建的内容。

许可证

Apache 2.0。Proxmox 是 Proxmox Server Solutions GmbH 的注册商标；本项目并非由 Proxmox Server Solutions GmbH 制作或认可。