Proxmox VE

---

“为什么数据库 VM 今天这么慢？” pve2 上的 VM 101（db）自 09:00 起平均 CPU 使用率为 94%，同期 pve2 的 IO 等待一直高于 30%。它的磁盘位于 local-lvm，该存储空间已使用 91%；昨晚备份到同一磁盘的任务仍在运行。要我展示备份任务的日志，还是规划将 VM 迁移到有 40 GiB 可用内存的 pve1？

用通俗的语言询问你的集群。助手会从 300 多种工具中选择合适的工具来查询信息；如果你允许，也可以进行更改。示例：

• 🩺 “检查一下集群的运行状况。”
• 📈 “哪些 VM 使用的内存最多？哪个节点的可用资源最多？”
• 💾 “哪些来宾系统没有备份？昨晚的备份成功了吗？”
• 🧹 “找出超过一个月的快照。”
• 🔐 “检查用户、API 令牌和权限，看看是否存在风险。”
• 🚀 “将 Debian 模板克隆为一台名为 web-02 的新 VM，分配 4 GB 内存并接入 VLAN 20。”

亮点

• 🐳 Docker 优先。 提供一个小巧的 distroless 镜像（ghcr.io/mattoddie/proxmox-mcp），支持 linux/amd64 和 linux/arm64。长时间运行的服务使用 Streamable HTTP，也可通过 docker run -i 使用 stdio。
• 🖱️ 一键安装 Claude Desktop。 每个版本都附带适用于 macOS、Windows 和 Linux 的 MCP Bundle（.mcpb）：打开后填写设置表单即可。无需 Docker。
• 🛡️ 默认安全。 除非启用写入功能，否则服务只读。删除操作需要启用第二个开关，在来宾系统内运行命令则需要启用第三个开关。未获准的工具不会注册，破坏性工具会标记出来，让 MCP 客户端在运行前征求确认；每项更改都可以通过 dry_run 预览并记录到审计日志中，密码和密钥则会从输出中脱敏。
• 🧰 覆盖广泛。 支持 19 个工具集：集群、节点、VM、容器、来宾 Agent、快照、存储、备份、任务、访问控制、防火墙、HA、SDN、Ceph、资源池、复制、通知、硬件和原始 API 工具。
• ⏱️ 感知任务状态。 启动、克隆、迁移和备份等长时间操作会作为 Proxmox 任务运行。工具会等待任务完成，并报告任务日志末尾的内容；也可以返回任务 ID，供之后跟进。
• 🎯 按 VMID 定位。 询问 VM 100 时，服务会查找它所在的节点。单节点安装完全不需要节点名称。
• 🎛️ 可调节。 只启用你需要的工具集；列表工具支持 search、fields 和 limit，让模型上下文保持精简且聚焦。
• 🔑 最小权限。 使用按 Proxmox 自身角色和 ACL 授权的专用 API 令牌，让 Proxmox 也能强制执行权限限制。
• 🧪 经过测试。 每次构建都会针对模拟的 Proxmox API 运行测试套件。

快速开始

你需要 Docker、Proxmox VE 8 或 9 服务器或集群，以及一个 MCP 客户端，例如 Claude Code。

1. 创建 API 令牌。 在任意节点上，以 root 身份创建一个只读用户和令牌：

pveum user add mcp@pve --comment "proxmox-mcp"
pveum acl modify / --users mcp@pve --roles PVEAuditor
pveum user token add mcp@pve mcp --privsep 0

从输出中复制令牌密钥。之后将无法再次查看。入门指南介绍了各种选项，包括可以进行更改的令牌。

2. 启动服务。

mkdir proxmox-mcp && cd proxmox-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/example.env -o .env
# Edit .env: set PROXMOX_URL, PROXMOX_TOKEN_ID (mcp@pve!mcp), PROXMOX_TOKEN_SECRET,
# a random MCP_AUTH_TOKEN (required; e.g. `openssl rand -hex 32`) and how to check the
# Proxmox certificate (required for https): PROXMOX_TLS_FINGERPRINT (recommended; the
# SHA-256 fingerprint from Node > System > Certificates), or PROXMOX_VERIFY_SSL=false
docker compose up -d

3. 连接助手。

claude mcp add --transport http proxmox http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

现在，在 Claude Code 中询问 “我的 Proxmox 集群运行得怎么样？”。

使用 Claude Desktop？ 跳过 Docker：从最新版本下载适用于你电脑的 .mcpb 捆绑包，打开后填写设置表单。请参阅 Claude Desktop。

使用 VS Code、Cursor 或 Codex？ 请参阅连接 MCP 客户端。不想运行服务？使用 docker run -i 配置 stdio 模式。

proxmox-mcp 已列入 MCP Registry，名称为 io.github.mattoddie/proxmox-mcp。因此，能够浏览该注册表的客户端可以安装它（作为通过 stdio 使用的 Docker 镜像，或 Claude Desktop 捆绑包），并询问所需设置。

启用更改

默认情况下，助手可以查看，但无法修改。要允许它进行更改，请将以下内容添加到 .env 并运行 docker compose up -d：

PROXMOX_ALLOW_WRITES=true    # start/stop guests, create, clone, migrate, reconfigure, snapshot, back up…
PROXMOX_ALLOW_DELETES=true   # also allow deleting guests, snapshots, backups and configuration (needs writes)
PROXMOX_ALLOW_EXEC=true      # also allow commands and file access inside VMs via the guest agent (needs writes)
PROXMOX_TOOLSETS=cluster,nodes,vms,containers,snapshots,backup,tasks   # optional: expose fewer tools
PROXMOX_AUDIT_LOG=/audit/audit.jsonl    # optional: log every change as JSON (mount ./audit; see compose.yaml)

每个会进行更改的工具都接受 dry_run，因此你可以先让助手展示更改，再决定是否执行。令牌也需要具备相应的 Proxmox 权限。在为生产集群启用写入操作前，请阅读安全。

功能

工具集	涵盖内容
cluster	集群概览、节点和来宾概况、数据中心选项、corosync 配置、指标服务器、批量来宾操作
nodes	节点状态和统计信息、服务、网络接口、DNS、时间、更新和软件源、订阅、证书和 ACME、日志、节点电源
vms	QEMU 虚拟机：状态、配置、电源、创建、克隆、磁盘、迁移、模板、cloud-init、统计信息
containers	LXC 容器：状态、配置、电源、创建、克隆、卷、迁移、模板、接口、统计信息
agent	QEMU 来宾 Agent：操作系统、网络和文件系统信息、冻结/修剪，以及（启用 exec 后的）命令和文件访问
snapshots	虚拟机和容器快照：列出、创建、回滚、删除，以及集群范围的旧快照视图
storage	存储定义和使用情况、卷、ISO 和模板下载、物理磁盘、SMART、ZFS 和 LVM
backup	vzdump 备份作业、临时备份、备份列表、还原、清理、无备份的来宾
tasks	Proxmox 任务：列出、检查、读取日志、等待和停止任务
access	用户、组、角色、ACL、API 令牌、域、有效权限、双重身份验证
firewall	数据中心、节点和来宾级别的规则、选项、别名、IP 集和安全组，以及防火墙日志
ha	高可用状态、资源、组和规则
sdn	SDN 区域、VNet、子网、控制器、IPAM 和 DNS、应用待处理的更改
ceph	Ceph 健康状态、OSD、存储池、监视器、管理器、元数据服务器、CephFS、标志
pools	资源池及其成员
replication	存储复制作业、状态和日志
notifications	通知目标和匹配器
hardware	PCI 和 USB 设备、媒介设备、资源映射、CPU 型号
raw	可调用任意 Proxmox API 路径的备用入口。默认关闭，除非 PROXMOX_TOOLSETS 中列出 raw（例如 all,raw）

有关所有工具和参数，请参阅**工具参考**。诸如 cluster_health_check、backup_audit 和 troubleshoot_guest 这样的现成提示词会串联工具，完成常见任务。

文档

文档也发布在 proxmox-mcp.mattoddie.dev/docs，并支持搜索。

🚀 快速入门	分步配置，从 API 令牌到提出第一个问题
🔌 连接 MCP 客户端	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio 模式
⚙️ 配置	所有环境变量、Docker secrets、工具集
🐳 部署	Compose、镜像标签、升级、TLS 反向代理、安全加固
💬 使用 proxmox-mcp	对话示例、提示词、任务、变更和机密的工作方式
🧰 工具参考	所有工具和提示词，均根据代码生成
🛡️ 安全	威胁模型、最小权限令牌、安全的写入配置
📡 兼容性	支持的 Proxmox VE 版本、Ceph、PBS、已知限制
🩹 故障排除	常见错误及其解决方法
🛠️ 开发	架构、添加工具、测试

正在使用手机？Proxly 是同一作者开发的免费 Proxmox VE iPhone 应用：监控节点、VM 和容器，启动和停止来宾系统，以及创建快照和备份，无需拿起笔记本电脑。

贡献

我们非常欢迎各种贡献，包括错误报告、来自你集群的兼容性报告、文档或新工具。请阅读贡献指南以开始参与，并遵守行为准则。如需报告漏洞，请参阅安全政策。请勿为此公开提交问题。

许可证

MIT © Matt Oddie

proxmox-mcp 是一个独立的社区项目，与 Proxmox Server Solutions GmbH 无关，也未获得其认可或赞助。Proxmox 是 Proxmox Server Solutions GmbH 的注册商标。