MCP Proxmox 服务器

使用 Python 实现的高级 Proxmox 模型上下文协议（MCP）服务器，提供丰富的 Proxmox 工具，用于发现、生命周期管理、网络配置、快照/备份、指标、池/权限以及编排。

• 引导参考：MCP 快速入门 (Python)
• 结构镜像：bsahane/mcp-ansible

快速开始

git clone https://github.com/bsahane/mcp-proxmox.git
cd mcp-proxmox

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt

# （可选）本地安装包
pip install -e .

.env 配置

• 复制 .env.example 到 .env 并编辑值：

cp .env.example .env

.env 键：

PROXMOX_API_URL="https://proxmox.example.com:8006"
PROXMOX_TOKEN_ID="root@pam!mcp-proxmox"
PROXMOX_TOKEN_SECRET="<secret>"
PROXMOX_VERIFY="true"
PROXMOX_DEFAULT_NODE="pve"
PROXMOX_DEFAULT_STORAGE="local-lvm"
PROXMOX_DEFAULT_BRIDGE="vmbr0"

注意事项：

• 使用具有适当 ACL 的 API 令牌；对于发现，PVEAuditor 在 / 足够；对于生命周期，授予更窄的角色（例如，在池上授予 PVEVMAdmin）。
• 使用 .env 可避免 zsh 历史扩展问题中的 ! 令牌 ID。

运行 MCP 服务器（标准输入输出）

首选（模块形式）：

source .venv/bin/activate
python -m proxmox_mcp.server

或已安装控制台脚本：

source .venv/bin/activate
proxmox-mcp

在 Cursor 中配置

编辑 ~/.cursor/mcp.json（便携示例）：

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

在 Claude for Desktop 中配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

工具参考

所有工具均可通过 MCP 访问。破坏性工具接受 confirm，大多数写操作支持 dry_run、wait、timeout、poll_interval。

以下格式按工具：

• 描述
• 示例问题 → 可能的答案（形状）

核心发现

• proxmox-list-nodes
  • 列出集群节点（名称、状态、CPU/RAM/磁盘摘要）
  • 示例："列出集群节点"
  • 答案：[ { "node": "pve", "status": "online", ... } ]
• proxmox-node-status
  • 详细节点健康状况（负载、运行时间、版本）
  • 示例：{ "node": "pve" }
  • 答案：{ "kversion": "...", "uptime": 123456, ... }
• proxmox-list-vms
  • 列出虚拟机（按节点、状态、名称子串过滤）
  • 示例：{ "node": "pve", "status": "running" }
  • 答案：[ { "vmid": 100, "name": "web01", ... } ]
• proxmox-vm-info
  • 通过 vmid 或 name 获取虚拟机详情（+可选节点），包括配置
  • 示例：{ "name": "web01" }
  • 答案：{ "selector": {...}, "config": {...} }
• proxmox-list-lxc
  • 列出 LXC 容器（可过滤）
  • 示例：{ "node": "pve" }
  • 答案：[ { "vmid": 50001, "name": "ct01", ... } ]
• proxmox-lxc-info
  • 通过 vmid 或 name 获取 LXC 详情（+可选节点）
  • 示例：{ "vmid": 100 }
  • 答案：{ "selector": {...}, "config": {...} }
• proxmox-list-storage
  • 列出存储（类型、空闲/已用）
  • 示例：{}
  • 答案：[ { "storage": "local-lvm", "type": "lvmthin", ... } ]
• proxmox-storage-content
  • 列出存储内容（ISO、模板、镜像）
  • 示例：{ "node": "pve", "storage": "local" }
  • 答案：[ { "volid": "local:iso/foo.iso", ... } ]
• proxmox-list-bridges
  • 列出节点桥接（vmbr...）
  • 示例：{ "node": "pve" }
  • 答案：[ { "iface": "vmbr0", ... } ]
• proxmox-list-tasks
  • 最近的任务（按节点、用户过滤）
  • 示例：{ "node": "pve", "limit": 20 }
  • 答案：[ { "upid": "UPID:...", "status": "OK" }, ... ]
• proxmox-task-status
  • 检查任务状态
  • 示例：{ "upid": "UPID:..." }
  • 答案：{ "status": "stopped", "exitstatus": "OK" }

虚拟机生命周期

• proxmox-clone-vm
  • 克隆模板虚拟机到新的 VMID/名称（支持目标节点、存储）
  • 示例：{ "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true }
  • 答案：{ "upid": "UPID:...", "status": {...} }
• proxmox-create-vm
  • 从 ISO/模板创建新虚拟机（最小配置）
  • 示例：{ "node": "pve", "vmid": 200, "name": "web02", "iso": "debian.iso", "confirm": true }
  • 答案：{ "upid": "UPID:..." }
• proxmox-delete-vm
  • 删除虚拟机（确认、清除）
  • 示例：{ "name": "web01", "purge": true, "confirm": true }
  • 答案：{ "upid": "UPID:..." }
• proxmox-start-vm / proxmox-stop-vm / proxmox-reboot-vm / proxmox-shutdown-vm
  • 管理电源状态（停止支持强制和超时）
  • 示例：{ "name": "web01", "wait": true }
  • 答案：{ "upid": "UPID:...", "status": {...} }
• proxmox-migrate-vm
  • 实时/离线迁移至另一节点
  • 示例：{ "name": "web01", "target_node": "pve2", "live": true }
  • 答案：{ "upid": "UPID:..." }
• proxmox-resize-vm-disk
  • 扩大目标磁盘（例如，scsi0）的大小（GB）
  • 示例：{ "name": "web01", "disk": "scsi0", "grow_gb": 10, "confirm": true, "wait": true }
  • 答案：{ "upid": "UPID:...", "status": {...} }
• proxmox-configure-vm
  • 设置白名单参数（核心数、内存、气球、netX、代理等）
  • 示例：{ "name": "web01", "params": { "memory": 4096, "cores": 4 }, "confirm": true }
  • 答案：{ "upid": "UPID:..." } 或 { "result": null }

LXC 生命周期

• proxmox-create-lxc
  • 从模板创建容器（CPU/内存、根文件系统大小、网络、存储）
  • 示例：{ "node": "pve", "vmid": 50050, "hostname": "ct01", "ostemplate": "debian-12.tar.zst", "confirm": true }
  • 答案：{ "upid": "UPID:..." }
• proxmox-delete-lxc / proxmox-start-lxc / proxmox-stop-lxc / proxmox-configure-lxc
  • 管理容器生命周期和配置

Cloud-init 和网络

• proxmox-cloudinit-set
  • 设置 CI 参数（ipconfig0、sshkeys、ciuser/cipassword）
  • 示例：{ "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true }
  • 答案：{ "upid": "UPID:..." } 或 { "result": null }
• proxmox-vm-nic-add / proxmox-vm-nic-remove
  • 添加/移除网卡（桥接、模型、VLAN）
• proxmox-vm-firewall-get / proxmox-vm-firewall-set
  • 获取/设置每个虚拟机的防火墙状态和规则

镜像、模板、快照、备份

• proxmox-upload-iso / proxmox-upload-template
  • 将 ISO 或 LXC 模板上传到存储
• proxmox-template-vm
  • 将虚拟机转换为模板
• proxmox-list-snapshots / proxmox-create-snapshot / proxmox-delete-snapshot / proxmox-rollback-snapshot
  • 管理快照；回滚支持 wait
• proxmox-backup-vm / proxmox-restore-vm
  • 运行 vzdump 并恢复存档

指标和监控

• proxmox-vm-metrics
  • 虚拟机的 RRD 指标（时间段、cf）
• proxmox-node-metrics
  • 节点的 RRD 指标

池、用户、权限

• proxmox-list-pools / proxmox-create-pool / proxmox-delete-pool / proxmox-pool-add / proxmox-pool-remove
• proxmox-list-users / proxmox-list-roles / proxmox-assign-permission

编排助手

• proxmox-wait-task
  • 直到完成/超时轮询任务
• proxmox-register-vm-as-host
  • 发射 JSON/INI 片段用于 Ansible 库存（主机名、IP、SSH 用户/密钥）
• proxmox-guest-exec（可选）
  • 通过 QEMU 客户端代理运行命令（需要客户端中的代理）

示例

• 列出节点：{} 对于 proxmox-list-nodes
• 节点 pve 上的虚拟机：{ "node": "pve" } 对于 proxmox-list-vms
• 克隆一个模板：{ "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true }
• 配置 Cloud-init IP：{ "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true }

注意事项

• 服务器使用标准输入输出传输；仅将 MCP 协议打印到标准输出。日志发送到标准错误。
• 认证使用您的环境变量和/或 .env 文件。
• 跨节点的名称冲突返回明确的错误，除非您指定了 node。

开发

# 按需进行代码检查/类型检查（默认不包含）

许可证

MIT