pve-mcp
Provides tools for managing a Proxmox VE cluster through its API: checking cluster/node/VM status, listing storage and ISOs, monitoring and waiting on tasks, and performing write operations such as VM power control (start/stop/shutdown/reboot/suspend/resume), cloning from templates, creating/deleting/rolling back snapshots, updating VM configuration, and permanently deleting VMs/CTs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pve-mcp list all running VMs on my Proxmox cluster"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pve-mcp — Proxmox VE MCP Server
用 Python 编写的 Proxmox VE MCP(Model Context Protocol)服务器。 在 VS Code / Copilot、Claude Desktop 等支持 MCP 的客户端里,用自然语言查看集群状态、管理虚拟机和快照。
传输方式:stdio
认证:API Token(推荐) 或 用户名/密码(ticket)
所有会产生副作用的工具都需要显式
confirm=true
功能
分类 | 工具 | 说明 |
连接 |
| 版本 / 连通性自检 |
集群 |
| 节点、仲裁、VM 数量统计 |
节点 |
| 节点 CPU / 内存 / 磁盘 / 运行时长 |
节点 |
| 单节点详情(含存储用量) |
客户机 |
| 列出 VM 与 LXC(可按节点/状态/类型过滤) |
客户机 |
| 单机状态 + 配置 |
客户机 |
| 快照列表 |
客户机 |
| 可克隆模板 |
客户机 |
| Guest Agent 网络接口 / OS 信息(仅 QEMU) |
存储 |
| 存储定义、容量、ISO |
任务 |
| 任务查询与等待 |
电源 |
| start / stop / shutdown / reboot / suspend / resume |
克隆 |
| 从模板或 VM 克隆 |
快照 |
| 快照增删回滚 |
配置 |
| 修改 VM 配置项(如 |
删除 |
| 永久销毁 VM/CT |
逃生口 |
| 任意 API 调用(默认关闭) |
Related MCP server: proxmox-mcp-server
安装
cd c:\Users\goyuj\Desktop\pve-mcp
python -m pip install -e .
# 或者只装依赖,直接 python -m pve_mcp 运行依赖:mcp>=2.0、httpx>=0.27(Python 3.10+)。
在 Proxmox 上创建 API Token
Web UI → 数据中心 → 权限 → API 令牌 → 添加,用户选
root@pam(或专用用户),取消勾选「特权分离」或随后单独授权。复制生成的 Secret(只显示一次),Token ID 形如
root@pam!mcp。授权(SSH 到 PVE 节点执行):
# 只读
pveum acl modify / --tokens 'root@pam!mcp' --roles PVEAuditor
# 需要开关机 / 快照 / 克隆 / 改配置
pveum acl modify / --tokens 'root@pam!mcp' --roles PVEVMAdmin配置
复制 .env.example 为 .env 并填写(服务器会自动加载项目根目录或当前目录的 .env):
PVE_HOST=https://192.168.1.10:8006
PVE_TOKEN_ID=root@pam!mcp
PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PVE_VERIFY_SSL=false # 自签证书时设为 false变量 | 默认值 | 说明 |
| —(必填) |
|
| — | Token 认证(推荐) |
| — | Ticket 认证(Token 未配置时使用,401 会自动重新登录) |
|
| 是否校验证书 |
|
| HTTP 超时(秒) |
| — | 省略 |
|
|
|
|
|
|
| — | 指定额外的 env 文件路径 |
也可以在 MCP 客户端的配置里直接写 env(VS Code 支持 ${input:...} / ${env:...} 占位符)。
VS Code
仓库内已提供 .vscode/mcp.json,打开工作区后即可在 MCP 服务器列表里启动 pve。
同样可以写入用户级 mcp.json:
{
"servers": {
"pve": {
"type": "stdio",
"command": "python",
"args": ["-m", "pve_mcp"],
"env": {
"PYTHONPATH": "c:\\Users\\goyuj\\Desktop\\pve-mcp",
"PVE_HOST": "https://192.168.1.10:8006",
"PVE_TOKEN_ID": "root@pam!mcp",
"PVE_TOKEN_SECRET": "xxxx"
}
}
}
}Claude Desktop / 其他客户端
{
"mcpServers": {
"pve": {
"command": "python",
"args": ["-m", "pve_mcp"],
"env": {
"PYTHONPATH": "c:\\Users\\goyuj\\Desktop\\pve-mcp",
"PVE_HOST": "https://192.168.1.10:8006",
"PVE_TOKEN_ID": "root@pam!mcp",
"PVE_TOKEN_SECRET": "xxxx"
}
}
}
}安装为可执行命令后(pip install -e .)也可以直接 command: "pve-mcp"。
安全设计
写操作(电源、克隆、快照、改配置、删除)必须传
confirm=true,否则直接拒绝,不会发出任何请求。PVE_READ_ONLY=true可整体冻结写操作。pve_api_request默认不可用,需要PVE_ALLOW_RAW_API=true。只接受相对 API 路径,禁止传入绝对 URL(防止凭据被发到别的地址)。
凭据只从环境变量 /
.env读取,不会出现在工具参数里;.env已在.gitignore中。
开发
python -m pip install -e ".[dev]"
python -m pytest -q代码结构:
pve_mcp/config.py — 环境变量解析、
.env加载、URL 规范化pve_mcp/client.py — PVE API 客户端(Token / Ticket 认证、错误映射、任务轮询)
pve_mcp/server.py — MCP 工具定义
tests/ — 使用
httpx.MockTransport的单元测试
License
本项目基于 MIT License 发布,Copyright (c) 2026 WindSnowLi。
提示:请勿提交你自己的
.env。本项目只提供.env.example,所有凭据都应通过环境变量或本机.env注入。
Available Tools
23 toolspve_api_requestBDestructive
Call an arbitrary PVE API path (escape hatch). Requires PVE_ALLOW_RAW_API=true.
Inputs: path (required), method (required), data, params. Returns: object
pve_clone_vmC
Clone a VM/container or template into a new VMID. Requires confirm=true.
Inputs: vmid (required), newid (required), full, kind, +7 more. Returns: object
pve_cluster_statusARead-only
Summarise cluster health: nodes, quorum, and guest counts by state.
Inputs: no named parameters. Returns: object
pve_create_snapshotB
Create a snapshot of a VM/container. Requires confirm=true.
Inputs: vmid (required), snapname (required), kind, node, +5 more. Returns: object
pve_delete_snapshotADestructive
Delete a snapshot (irreversible). Requires confirm=true.
Inputs: vmid (required), snapname (required), kind, node, +3 more. Returns: object
pve_delete_vmCDestructive
Permanently destroy a VM/container. Requires confirm=true.
Inputs: vmid (required), kind, node, wait, +4 more. Returns: object
pve_get_vmBRead-only
Get current status (and config) of a VM or container.
Inputs: vmid (required), kind, node, include_config. Returns: object
pve_guest_agent_networkBRead-only
Read network interfaces reported by the QEMU guest agent.
Inputs: vmid (required), node. Returns: object
pve_guest_agent_osinfoBRead-only
Read OS information reported by the QEMU guest agent.
Inputs: vmid (required), node. Returns: object
pve_list_isosBRead-only
List ISO images available on a storage (node is needed for node-scoped storages).
Inputs: storage (required), node. Returns: object
pve_list_nodesARead-only
List cluster nodes with CPU, memory, disk and uptime.
Inputs: no named parameters. Returns: object
pve_list_snapshotsCRead-only
List snapshots of a VM or container.
Inputs: vmid (required), kind, node. Returns: object
pve_list_storageARead-only
List storage definitions; when node is known, include capacity usage on that node.
Inputs: node. Returns: object
pve_list_tasksCRead-only
List recent cluster/node tasks, optionally filtered by guest.
Inputs: node, vmid, limit. Returns: object
pve_list_templatesBRead-only
List templates available for cloning.
Inputs: node. Returns: object
pve_list_vmsBRead-only
List VMs and LXC containers in the cluster, optionally filtered.
Inputs: kind, node, status, include_templates. Returns: object
pve_node_statusBRead-only
Show detailed status for one node, optionally with its storage usage.
Inputs: node, include_storage. Returns: object
pve_rollback_snapshotBDestructive
Roll a guest back to a snapshot, discarding later changes. Requires confirm=true.
Inputs: vmid (required), snapname (required), kind, node, +3 more. Returns: object
pve_task_statusBRead-only
Show a task's status (running/stopped, exit status) and optionally its log tail.
Inputs: upid (required), node, log_limit, include_log. Returns: object
pve_update_vmB
Update guest configuration keys (e.g. {"memory": 4096, "onboot": 1}). Requires confirm=true.
Inputs: vmid (required), settings (required), kind, node, +2 more. Returns: object
pve_versionARead-only
Return the Proxmox VE version of the connected host (connectivity check).
Inputs: no named parameters. Returns: object
pve_vm_powerB
Change guest power state (start/stop/shutdown/reboot/suspend/resume). Requires confirm=true.
Inputs: vmid (required), action (required), kind, node, +3 more. Returns: object
pve_wait_taskBRead-only
Wait for a task to finish and return its exit status.
Inputs: upid (required), node, timeout. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool targets a distinct resource+action pair: reads (version, cluster_status, node_status, get_vm), enumerations (nodes, VMs, storage, ISOs, templates, snapshots, tasks), and guarded mutations (power, clone, snapshot create/delete/rollback, update, delete). The only mild overlaps—task_status vs wait_task and the api_request escape hatch—are clearly differentiated by their descriptions, so an agent can select confidently.
All 23 tools share a uniform pve_ prefix and snake_case, with mostly verb_noun order (list_vms, get_vm, create_snapshot, delete_vm, wait_task). A few noun-first status/reader names (pve_version, pve_node_status, pve_task_status, pve_guest_agent_network) deviate slightly, but the pattern stays highly readable and predictable.
23 tools is on the heavy side for the 16-25 band, but every tool maps to a real Proxmox operation across nodes, guests, storage, snapshots, tasks and guest-agent reads, so none feel gratuitous. A couple of niche readers (guest_agent_osinfo/network) could be merged, but the set is well-scoped overall.
The surface covers reads plus a solid mutation lifecycle (power, clone, update, delete, snapshot create/delete/rollback) for guests, with strong task and node/storage introspection. Notable gaps for a Proxmox domain include backup/restore, VM creation from scratch (clone-only), and migration, though the documented pve_api_request escape hatch lets agents work around these.
Related MCP Connectors
Skills, agents and memory in the cloud, plus a gateway to your other MCP servers.
MCP-first control plane for ProAgentStore agents and private instances.
Marketplace and infrastructure for MCP servers and skills: deploy, host, monetize, analytics.
Manage uptime monitors, incidents and status pages from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Proxmox VE virtual machines via MCP and OpenAPI, supporting operations like start, stop, clone, and snapshot.6MIT
- AlicenseAqualityAmaintenanceEnables management of Proxmox VE virtual environments (VMs, containers, storage, snapshots, etc.) through natural language via MCP, with async task polling for reliable write operations.1653 npm1MIT
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE environments, including VMs, containers, storage, and cluster operations through natural language.7653 npmMIT
- AlicenseAqualityBmaintenanceEnables natural language interaction with Proxmox VE clusters for managing VMs, containers, storage, and snapshots.2711 npm3MIT