Skip to main content
Glama

pve-mcp — Proxmox VE MCP Server

License: MIT Python

用 Python 编写的 Proxmox VE MCP(Model Context Protocol)服务器。 在 VS Code / Copilot、Claude Desktop 等支持 MCP 的客户端里,用自然语言查看集群状态、管理虚拟机和快照。

  • 传输方式:stdio

  • 认证:API Token(推荐) 或 用户名/密码(ticket)

  • 所有会产生副作用的工具都需要显式 confirm=true

功能

分类

工具

说明

连接

pve_version

版本 / 连通性自检

集群

pve_cluster_status

节点、仲裁、VM 数量统计

节点

pve_list_nodes

节点 CPU / 内存 / 磁盘 / 运行时长

节点

pve_node_status

单节点详情(含存储用量)

客户机

pve_list_vms

列出 VM 与 LXC(可按节点/状态/类型过滤)

客户机

pve_get_vm

单机状态 + 配置

客户机

pve_list_snapshots

快照列表

客户机

pve_list_templates

可克隆模板

客户机

pve_guest_agent_*

Guest Agent 网络接口 / OS 信息(仅 QEMU)

存储

pve_list_storage / pve_list_isos

存储定义、容量、ISO

任务

pve_list_tasks / pve_task_status / pve_wait_task

任务查询与等待

电源

pve_vm_power

start / stop / shutdown / reboot / suspend / resume

克隆

pve_clone_vm

从模板或 VM 克隆

快照

pve_create_snapshot / pve_delete_snapshot / pve_rollback_snapshot

快照增删回滚

配置

pve_update_vm

修改 VM 配置项(如 memory、cores、onboot)

删除

pve_delete_vm

永久销毁 VM/CT

逃生口

pve_api_request

任意 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

  1. Web UI → 数据中心 → 权限 → API 令牌 → 添加,用户选 root@pam(或专用用户),取消勾选「特权分离」或随后单独授权。

  2. 复制生成的 Secret(只显示一次),Token ID 形如 root@pam!mcp。

  3. 授权(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

变量

默认值

说明

PVE_HOST

—(必填)

host 或完整 URL,缺省补 https:// 与 :8006

PVE_TOKEN_ID / PVE_TOKEN_SECRET

—

Token 认证(推荐)

PVE_USERNAME / PVE_PASSWORD

—

Ticket 认证(Token 未配置时使用,401 会自动重新登录)

PVE_VERIFY_SSL

true

是否校验证书

PVE_TIMEOUT

30

HTTP 超时(秒)

PVE_DEFAULT_NODE

—

省略 node 参数时使用的节点

PVE_READ_ONLY

false

true 时禁用所有写操作

PVE_ALLOW_RAW_API

false

true 时启用 pve_api_request

PVE_ENV_FILE

—

指定额外的 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

代码结构:

License

本项目基于 MIT License 发布,Copyright (c) 2026 WindSnowLi。

提示:请勿提交你自己的 .env。本项目只提供 .env.example,所有凭据都应通过环境变量或本机 .env 注入。

Available Tools

23 tools
pve_api_requestB
Destructive

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_statusA
Read-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_snapshotA
Destructive

Delete a snapshot (irreversible). Requires confirm=true.

Inputs: vmid (required), snapname (required), kind, node, +3 more. Returns: object

pve_delete_vmC
Destructive

Permanently destroy a VM/container. Requires confirm=true.

Inputs: vmid (required), kind, node, wait, +4 more. Returns: object

pve_get_vmB
Read-only

Get current status (and config) of a VM or container.

Inputs: vmid (required), kind, node, include_config. Returns: object

pve_guest_agent_networkB
Read-only

Read network interfaces reported by the QEMU guest agent.

Inputs: vmid (required), node. Returns: object

pve_guest_agent_osinfoB
Read-only

Read OS information reported by the QEMU guest agent.

Inputs: vmid (required), node. Returns: object

pve_list_isosB
Read-only

List ISO images available on a storage (node is needed for node-scoped storages).

Inputs: storage (required), node. Returns: object

pve_list_nodesA
Read-only

List cluster nodes with CPU, memory, disk and uptime.

Inputs: no named parameters. Returns: object

pve_list_snapshotsC
Read-only

List snapshots of a VM or container.

Inputs: vmid (required), kind, node. Returns: object

pve_list_storageA
Read-only

List storage definitions; when node is known, include capacity usage on that node.

Inputs: node. Returns: object

pve_list_tasksC
Read-only

List recent cluster/node tasks, optionally filtered by guest.

Inputs: node, vmid, limit. Returns: object

pve_list_templatesB
Read-only

List templates available for cloning.

Inputs: node. Returns: object

pve_list_vmsB
Read-only

List VMs and LXC containers in the cluster, optionally filtered.

Inputs: kind, node, status, include_templates. Returns: object

pve_node_statusB
Read-only

Show detailed status for one node, optionally with its storage usage.

Inputs: node, include_storage. Returns: object

pve_rollback_snapshotB
Destructive

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_statusB
Read-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_versionA
Read-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_taskB
Read-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

    B3.4/5.0

    Scored across 23 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    Related MCP Servers