mcp-proxmox 是一个面向 Proxmox VE 集群管理的 MCP（Model Context Protocol）服务器，允许用户通过 Claude、Cursor、Cline 等 AI 助手以自然语言完成基础设施的配置、管理与监控。
用途 通过自然语言对 Proxmox VE 集群进行日常运维，包括创建虚拟机与容器、管理快照、浏览存储、备份与恢复、模板与 cloud-init 配置、防火墙规则管理以及节点间迁移等。
主要能力
- 虚拟机与容器：创建、删除、克隆、调整 CPU/内存/磁盘、启停与重启。
- 快照：创建、回滚、删除。
- 存储：列出存储池、浏览内容、查看可用 ISO 镜像。
- 备份与恢复：备份虚拟机、查看备份、恢复备份。
- 命令执行：在虚拟机内执行命令（需 qemu-guest-agent，仅支持 QEMU 虚拟机，不支持 LXC）。
- 控制台交互：截图、发送键盘输入（仅 QEMU 虚拟机，需 VM.Console 权限，文本输入基于 US 键盘布局，不支持非 ASCII 字符）。
- 模板与 cloud-init：列出模板、将虚拟机转换为模板、配置 cloud-init 参数。
- 防火墙：查看与添加防火墙规则。
- 迁移：在节点之间迁移虚拟机/容器。
- 节点与任务：查看节点状态、任务、网络桥接等。
使用方式
- 在 Proxmox Web UI 中创建 API Token：进入 Datacenter > Permissions > API Tokens，点击 Add 为用户创建令牌。可取消勾选 "Privilege Separation" 以获得完整权限，或按需分配权限（如 VM.Audit、VM.PowerMgmt、VM.Snapshot、VM.Allocate、VM.Clone、Datastore.Audit、Datastore.AllocateSpace、Sys.Audit、VM.Config.Disk、VM.Config.CPU、VM.Config.Memory、VM.Monitor、VM.Console、VM.Migrate、Sys.Modify、VM.Config.Cloudinit）。
- 设置环境变量或创建 .env 文件，至少包含 PROXMOX_HOST、PROXMOX_TOKEN_ID、PROXMOX_TOKEN_SECRET。
- 在 MCP 客户端中配置：Claude Desktop 可添加到 ~/.claude/claude_desktop_config.json；Claude Code 可添加到 .claude/settings.json 或 ~/.claude/settings.json；Cursor 可在 Settings > MCP 中使用相同配置。
- 连接后即可用自然语言向 AI 助手发出指令，例如列出虚拟机及状态、查看内存占用、关闭容器、创建快照、查看 CPU 使用、创建新虚拟机、克隆、备份、恢复、执行命令、截图、调整资源、管理防火墙、迁移、管理模板与 cloud-init 等。
破坏性操作确认 stop_guest、reboot_guest、rollback_snapshot、delete_snapshot、delete_guest、resize_guest、restore_backup、delete_firewall_rule、migrate_guest、create_template 等操作需要显式传入 confirm=true。首次调用会返回影响警告，只有第二次带确认的调用才会执行。
适用场景 适用于需要以对话方式管理 Proxmox VE 集群的运维人员、家庭实验室用户及开发团队，尤其适合快速查询状态、执行常规运维任务和自动化操作。
限制与注意事项
- exec_command 需要虚拟机内安装并运行 qemu-guest-agent，且不支持 LXC 容器。
- 控制台工具仅支持 QEMU 虚拟机，文本输入依赖 US 键盘布局，不支持非 ASCII 输入。
- 常见问题：缺少环境变量、403 权限不足、guest-agent 或 LXC 导致 exec_command 失败、mcp.server.fastmcp 模块缺失（需升级到 mcp-proxmox 1.2.2 或更高版本，其固定 mcp<2）、自签名证书或连接错误（Proxmox 常用端口 8006，家庭实验室可设置 PROXMOX_VERIFY_SSL=false）。
