AI导哈

Proxmox服务器管理工具

MCP Proxmox Server是一个Python开发的Proxmox工具集，提供虚拟机生命周期管理、网络配置、快照备份、监控指标和权限管理等功能，适用于虚拟化环境的管理和自动化。

  • by bsahane
  • Python
  • 本地部署
  • 21 星标
  • 更新于
在 GitHub 查看 bsahane/mcp-proxmox

使用说明

MCP Proxmox服务器

Python中的高级Proxmox模型上下文协议（MCP）服务器公开了丰富的Proxmox实用程序，用于发现、生命周期、网络、快照/备份、指标、池/权限和编排。

快速启动

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

# (Optional) install the package locally
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服务器（stdio）

首选（模块形式）：

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

或安装控制台脚本：

source .venv/bin/activate
proxmox-mcp

在游标中配置

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

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

在Claude中配置桌面版

增添 ~/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
    • 通过以下方式获取VM详细信息 vmid 或 name （+可选节点），包括配置
    • 例子： { "name": "web01" }
    • 答案： { "selector": {...}, "config": {...} }
  • proxmox-list-lxc
    • 列出LXC容器（可过滤）
    • 例子： { "node": "pve" }
    • 答案： [ { "vmid": 50001, "name": "ct01", ... } ]
  • proxmox-lxc-info
    • 通过以下方式获取LXC详细信息 vmid 或 name （+可选节点）
    • 例子： { "vmid": 50001 }
    • 答案： { "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" }

VM生命周期

  • proxmox-clone-vm
    • 将模板VM克隆到新的VMID/名称（支持目标节点、存储）
    • 例子： { "source_vmid": 101, "new_vmid": 50009, "name": "web01", "storage": "local-lvm", "confirm": true, "wait": true }
    • 答案： { "upid": "UPID:...", "status": {...} }
  • proxmox-create-vm
    • 从ISO/模板创建新VM（最小配置）
    • 例子： { "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/mem、rootfs大小、网络、存储）
    • 例子： { "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
    • 管理容器生命周期和配置

云初始化和网络

  • 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
    • 添加/删除NIC（网桥、型号、VLAN）
  • proxmox-vm-firewall-get / proxmox-vm-firewall-set
    • 获取/设置每个VM的防火墙状态和规则

图像、模板、快照、备份

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

度量和监控

  • proxmox-vm-metrics
    • VM的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
    • 为Ansible清单（主机名、IP、SSH用户/密钥）发送JSON/INI代码段
  • 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 }
  • 配置云初始化IP： { "name": "web01", "ipconfig0": "ip=192.168.1.50/24,gw=192.168.1.1", "confirm": true }

备注

  • 服务器使用stdio传输；仅将MCP协议打印到stdout。日志将转到stderr。
  • 身份验证使用您的环境变量和/或 .env 文件。
  • 除非您指定，否则节点之间的名称冲突将返回明显的错误 node.

发展

# Lint/type-check as needed (not included by default)

许可证

麻省理工学院

相关 MCP