proxmox-ve-mcp

一个 MCP 服务器，将一个或多个 Proxmox VE 主机暴露为 LLM 客户端可以调用的工具 —— 盘点节点、虚拟机、存储和网络桥接，读取实时状态，并创建、克隆、启动、停止和删除虚拟机和容器。

它通过 Streamable HTTP 使用 MCP 协议，因此作为网络上的独立服务运行，而不是作为单个客户端的本地子进程。

为 universal-network-director 构建，这是一个基于聊天的多供应商网络管理器，每次写入操作都有人工审批门控 —— 但它是一个独立的 MCP 服务器，可与任何 MCP 客户端配合使用。

与 Proxmox Server Solutions GmbH 无关联、未经其认可或支持。 “Proxmox”和“Proxmox VE”是其各自所有者的商标，此处仅用于描述该软件与之通信的对象。

在指向生产环境之前请阅读此内容

二十四个工具中有十二个会改变状态，并且此服务器在执行之前不会询问。 没有确认，也没有试运行。如果模型决定调用其中一个，就会发生。

三种处理方法，按实际帮助程度排序：

1. 将 Proxmox API 令牌的作用域设为只读。 这是真正的控制，存在于 Proxmox 上，而非此代码中。为令牌分配路径 / 的内置 PVEAuditor 角色，那么无论任何模型决定什么，每个写入工具都会在 API 层面失败。除非你明确希望写入操作生效，否则请执行此操作。

2. 使用受保护虚拟机黑名单。 config/protected-vms.json 列出了写入工具拒绝触碰的虚拟机，在本地检查，在任何后端调用之前 —— 因此即使有人误批准，它仍然有效。如果文件缺失或无法解析，将拒绝所有虚拟机写入，而不是静默地不保护任何东西。请参见下文。

3. 在客户端中设置写入门控。 每个改变状态的工具都带有前缀 write_。这个前缀正是此代码库的约定，以便客户端可以匹配它并在执行前将这些调用路由到人工审批步骤。此服务器故意不自行执行此操作 —— 它没有用户可询问。

MCP 端点没有身份验证

此服务器将其工具暴露给任何能访问其端口的人。MCP 端没有令牌、客户端认证、TLS。

因此 MCP_HOST 默认为 127.0.0.1。容器映像设置为 0.0.0.0，因为它必须这样做，这意味着 发布容器的端口会将一个未经身份验证的虚拟机管理程序控制面板暴露在该接口上。 将其保留在与客户端相同的内部网络上，或者在其前面终止 TLS 和身份验证。

多主机设计

Proxmox 集群共享一个 API，但许多设置在不同子网上运行多个独立主机，它们之间没有集群。此服务器为每个主机保存一个连接，由简短的自由格式 标签 标识，每个工具都使用该标签来选择要与哪个主机通信。

一个主机由一对环境变量定义：

PROXMOX_SERVER1_URL=https://pve1.example.com:8006
PROXMOX_SERVER1_TOKEN='automation@pve!mcp=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

PROXMOX_<LABEL>_URL 中的 <LABEL> 小写后成为工具使用的 host 值（上面示例中的 server1）。添加第三个主机，只需添加第三对 —— 无需代码更改。根据站点命名它们，以便模型和日志清晰可读。

令牌是整个 user@realm!tokenid=secret 字符串，在创建时仅显示一次，位于 Datacenter → Permissions → API Tokens 下。认证是无状态的：每个请求都携带 Authorization: PVEAPIToken=... 头。没有登录调用，也没有 CSRF 令牌 —— 那是用户名/密码 会话 路径，此代码故意不使用。

对于使用自签名证书的主机，设置 PROXMOX_VERIFY_TLS=false。默认为开启。

受保护虚拟机黑名单

config/protected-vms.json 以只读方式挂载到容器中，包含写入工具不得触碰的虚拟机：

{
  "protected_vms": [
    {
      "host": "server1",
      "vmid": 100,
      "name": "example-mcp-host",
      "reason": "EXAMPLE -- the VM this MCP server itself runs in"
    }
  ]
}

host 是来自 list_hosts 的 标签，而不是 Proxmox 节点名称。reason 在拒绝消息中原样显示，因此请为遇到它的人编写。

此文件应被跟踪在 git 中。它最初作为未跟踪的 .env 中的环境变量存在，这意味着保护在全新克隆后无法保留，并且空列表看起来与填充的列表完全相同。现在，如果文件缺失或无法解析，将拒绝 所有 虚拟机写入；空列表是允许的，但在启动时会记录一条响亮的警告。

此处提供的条目是示例。在将其指向任何你关心的内容之前，请替换它们。

运行

docker build -t proxmox-ve-mcp .
docker run --rm \
  -e PROXMOX_SERVER1_URL=https://pve1.example.com:8006 \
  -e PROXMOX_SERVER1_TOKEN='automation@pve!mcp=...' \
  -e PROXMOX_VERIFY_TLS=false \
  -v "$PWD/config/protected-vms.json:/app/config/protected-vms.json:ro" \
  -p 127.0.0.1:8002:8002 \
  proxmox-ve-mcp

或者将 pip install -r requirements.txt 指向虚拟环境，然后直接运行 python server.py。

测试

独立脚本，无需 pytest。在容器中运行它们，以便它们拥有客户端所需的 PROXMOX_* 环境：

docker run --rm proxmox-ve-mcp python test_network_bridges.py
docker run --rm proxmox-ve-mcp python test_media_in_use.py
docker run --rm proxmox-ve-mcp python test_client.py

离线部分使用虚构的接口和虚拟机列表，在未配置主机时通过。在线部分读取你 PROXMOX_* 变量指向的内容，当未配置任何内容时 干净地跳过 —— 将它们指向一个真实主机，以测试无法伪造的唯一区别：桥接是上行还是隔离。

设计说明

• /cluster/resources 是清单主干。 一次调用返回所有 VM、容器、节点和存储，这些已经标记了节点、vmid 和类型。它在独立主机上也能工作（它报告那个节点），因此使用此方法而不是逐个节点遍历 /nodes → /nodes/{node}/qemu。

• list_network_bridges 存在是因为 NIC 连接错误的桥接意味着你无法访问的虚拟机。 它针对每个桥接报告其是否有成员端口（一种离开主机的途径）或是隔离段 —— 这决定了新虚拟机是否可访问。

• VLAN 标签失败时关闭。 在非 bridge_vlan_aware 的桥接上设置 tag= 会被 Proxmox 接受，然后静默地不携带 —— 当要求隔离时，未标记的流量反而通行。写入路径会拒绝这种操作而不是警告，并且如果无法读取桥接列表进行检查也会拒绝。

• 写入是异步的。 大多数返回 Proxmox UPID；使用 get_task_status 轮询而不是假设完成。

• 虚拟机写入在一个守护之后运行。 一个单一的包装器执行受保护虚拟机检查和 vmid→节点/类型解析，因此单个工具不会忘记守护，也无法为受保护的虚拟机到达后端。

许可证

Apache-2.0。参见 LICENSE。