mcp-proxmox

mcp-proxmox

用于通过 Claude、Cursor 和 Cline 等 AI 助手管理 Proxmox VE 集群的 MCP 服务。

通过自然语言配置、管理和监控整个 Proxmox 基础设施。创建 VM 和容器、管理快照、浏览存储等。

快速开始

# Run directly with uvx (no install needed)
uvx mcp-proxmox

# Or install with pip
pip install mcp-proxmox

配置

设置以下环境变量（或创建 .env 文件）：

PROXMOX_HOST=192.168.1.100          # Your Proxmox VE host
PROXMOX_TOKEN_ID=user@pam!mcp       # API token ID
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # API token secret

可选：

PROXMOX_PORT=8006                   # Default: 8006
PROXMOX_VERIFY_SSL=false            # Default: false

创建 Proxmox API 令牌

1. 登录 Proxmox Web UI
2. 前往 数据中心 > 权限 > API 令牌
3. 点击 添加，为你的用户创建令牌
4. 若要获得完整访问权限，请取消勾选“权限分离”；也可以分配特定权限：
   • VM.Audit — 读取 VM/CT 状态和配置
   • VM.PowerMgmt — 启动/停止/关机/重启
   • VM.Snapshot — 创建/回滚/删除快照
   • VM.Allocate — 创建/删除/克隆 VM 和容器
   • VM.Clone — 克隆操作
   • Datastore.Audit — 列出存储并浏览内容
   • Datastore.AllocateSpace — 为新 VM/CT 分配磁盘空间
   • Sys.Audit — 读取节点状态和任务
   • VM.Config.Disk — 调整磁盘大小
   • VM.Config.CPU — 更改 CPU 分配
   • VM.Config.Memory — 更改内存分配
   • VM.Monitor — 访问 QEMU 监视器（用于获取指标）
   • VM.Console — 控制台交互工具（屏幕截图、键盘输入）
   • VM.Migrate — 在节点间迁移 VM/CT
   • Sys.Modify — 管理防火墙规则
   • VM.Config.Cloudinit — 配置 cloud-init 参数

集成

Claude Desktop

添加到 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "proxmox": {
      "command": "uvx",
      "args": ["mcp-proxmox"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "user@pam!mcp",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Claude Code

添加到 .claude/settings.json 或 ~/.claude/settings.json：

{
  "mcpServers": {
    "proxmox": {
      "command": "uvx",
      "args": ["mcp-proxmox"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "user@pam!mcp",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Cursor

在 Cursor Settings > MCP 中添加，配置与上述相同。

可用工具

发现

工具	描述
list_nodes	列出集群中的所有节点及其 CPU、内存和运行时间
get_node_status	节点详细信息：CPU 型号、内存、磁盘、版本
list_vms	列出 QEMU VM（按节点或状态筛选）
list_containers	列出 LXC 容器（按节点或状态筛选）
get_guest_status	按 VMID 获取 VM/CT 的详细状态（自动检测类型和节点）

生命周期

工具	描述
start_guest	启动已停止的 VM 或容器
stop_guest	强制停止（需要确认）
shutdown_guest	通过 ACPI/init 优雅关机
reboot_guest	重启（需要确认）

存储

工具	描述
list_storages	列出存储池及其容量和使用情况（按节点筛选）
list_storage_content	浏览 ISO、模板、备份和磁盘映像

配置资源

工具	描述
create_vm	创建 QEMU VM，可配置 CPU、内存、磁盘、ISO 和网络
create_container	根据模板创建 LXC 容器
clone_guest	克隆 VM 或 CT（完整克隆或链接克隆，支持跨节点操作）
delete_guest	永久删除已停止的 VM 或 CT（需要确认）

备份与恢复

工具	描述
list_backups	列出备份文件（按节点、存储或 VMID 筛选）
create_backup	创建 vzdump 备份（快照/挂起/停止模式，zstd/lzo/gzip）
restore_backup	从备份文件恢复 VM 或 CT（需要确认）

命令执行

工具	描述
exec_command	通过 guest agent 在 QEMU VM 内运行命令

注意：exec_command 要求在 VM 内安装并运行 qemu-guest-agent。由于 Proxmox API 的限制，不支持 LXC 容器。

控制台交互

工具	描述
vm_screenshot	截取 QEMU VM 显示画面的 PNG 屏幕截图（登录提示、启动消息、安装程序、GUI）
vm_send_key	向 VM 控制台发送按键或组合键（需要确认）
vm_send_text	在 VM 控制台输入 ASCII 文本（US 布局；需要确认）

注意： 控制台工具无需 qemu-guest-agent，只需要 VM.Console 权限。vm_screenshot 会打开与 Proxmox Web UI 使用的相同 VNC WebSocket 隧道（基于 DES 的 VNC 身份验证，RFB 3.8），并使用纯标准库实现（自定义 WebSocket 客户端 + DES）。仅支持 QEMU VM。文本输入取决于键盘布局：vm_send_text 会将 ASCII 映射到 US 键盘布局（大写字母和符号使用 Shift 映射）；发送键协议不支持非 ASCII 输入（例如西里尔字母）。

快照

工具	描述
list_snapshots	列出 VM/CT 的所有快照
create_snapshot	创建新快照
rollback_snapshot	回滚到某个快照（需要确认）
delete_snapshot	删除快照（需要确认）

网络

工具	描述
list_networks	列出节点上的网桥、绑定接口和物理接口

调整大小

工具	描述
resize_guest	调整 VM 或容器的 CPU、内存和/或磁盘大小（需要确认）

监控

工具	描述
get_guest_metrics	随时间变化的 CPU、内存、网络和磁盘 I/O 指标
list_tasks	节点上的近期任务（备份、迁移等）

防火墙

工具	描述
list_firewall_rules	列出 VM/CT、节点或集群的防火墙规则
add_firewall_rule	添加防火墙规则（动作、方向、协议、端口、源/目标）
delete_firewall_rule	按位置删除防火墙规则（需要确认）

迁移

工具	描述
migrate_guest	将 VM/CT 实时迁移或离线迁移到另一节点（需要确认）

模板与 Cloud-init

工具	描述
list_templates	列出所有可用于克隆的 VM 模板
create_template	将已停止的 VM 转换为模板（需要确认，且不可逆）
configure_cloud_init	为 VM 设置用户、密码、SSH 密钥、IP 配置和 DNS

安全

具有破坏性的操作（stop_guest、reboot_guest、rollback_snapshot、delete_snapshot、delete_guest、resize_guest、restore_backup、delete_firewall_rule、migrate_guest、create_template）都需要显式设置 confirm=true。首次调用会返回说明影响的警告；只有第二次调用并确认后，才会执行操作。

示例

连接后，你可以向 AI 助手提问：

• “列出我的所有 VM 及其状态”
• “VM 100 正在使用多少内存？”
• “关闭容器 105”
• “为 VM 200 创建一个名为 before-upgrade 的快照”
• “显示 VM 100 过去一天的 CPU 使用情况”
• “节点 pve 最近运行了哪些任务？”
• “哪些 VM 已停止？”
• “我有哪些存储池？它们的空间使用情况如何？”
• “显示可用的 ISO 镜像”
• “创建一个新的 Ubuntu VM，配置 4 个核心和 8GB RAM”
• “将 VM 100 克隆为测试环境”
• “从模板创建一个 Debian 容器”
• “删除旧的测试 VM 999”
• “将 VM 100 备份到 zfs-backup-storage”
• “显示 VM 200 的所有备份”
• “恢复容器 101 的最新备份”
• “在 VM 100 上运行 df -h”
• “检查 nginx 是否在 VM 200 上运行”
• “为 VM 100 截一张屏幕截图，这样我就能看到控制台”
• “VM 卡在登录提示符了——输入 root 并按 Enter”
• “显示节点 pve 上的网络桥接”
• “给 VM 100 增加 CPU——将其提升到 8 个核心”
• “给容器 101 增加 50GB 磁盘空间”
• “显示 VM 100 上的防火墙规则”
• “允许容器 101 上的 TCP 端口 443”
• “将 VM 200 迁移到节点 pve2”
• “列出集群中的所有模板”
• “将 VM 102 转换为模板”
• “为 VM 100 设置 cloud-init：用户 admin、IP dhcp、DNS 8.8.8.8”

故障排除

Missing required environment variables

此错误表示服务器进程无法获取一个或多个必需的连接设置。将 .env.example 复制为 .env，然后设置 PROXMOX_HOST、PROXMOX_TOKEN_ID 和 PROXMOX_TOKEN_SECRET。如果直接配置 MCP 客户端，请确保相同的变量存在于该客户端的 env 块中。

403 Permission check failed

403 通常表示 API 令牌有效，但没有执行所请求操作所需的 Proxmox 权限。请重新查看 创建 Proxmox API 令牌，并取消选中“Privilege Separation”以获得完整访问权限，或分配其中列出的特定权限，例如 VM.Audit、VM.PowerMgmt、VM.Snapshot，或数据存储操作所需的存储权限。

exec_command 因 guest-agent 或 LXC 问题失败

exec_command 仅适用于已安装并运行 qemu-guest-agent 的 QEMU VM。如果工具报告 QEMU guest agent 无响应，请在 VM 中启动或安装该 Agent，然后重试。此 Proxmox API 路径不支持 LXC 容器，因此请改用其他容器访问方式。

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

MCP Python SDK 2.0 移除了 mcp-proxmox 1.2.1 及更早版本导入的 mcp.server.fastmcp 模块。全新安装（uvx mcp-proxmox、uv tool install、pip install）会解析到 mcp 2.x，并在启动时失败——在 Claude Desktop 中，这只会显示为“Server disconnected”。请升级到 mcp-proxmox 1.2.2 或更高版本，该版本将 mcp 固定为 <2。如果必须继续使用较旧的 mcp-proxmox，请自行限制 SDK 版本：uvx --with "mcp<2" mcp-proxmox。

自签名证书或连接错误

Proxmox 通常使用端口 8006，因此请检查 PROXMOX_HOST 和 PROXMOX_PORT 是否指向与 Proxmox Web 界面相同的端点。对于使用自签名证书的家庭实验室集群，请将 PROXMOX_VERIFY_SSL=false 保持不变或显式设置。只有在 Proxmox 证书链最终连接到运行环境信任的 CA 时，才使用 PROXMOX_VERIFY_SSL=true。

开发

git clone https://github.com/antonio-mello-ai/mcp-proxmox.git
cd mcp-proxmox
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/

许可证

MIT