内容
# proxmox-mcp
一个 [MCP](https://modelcontextprotocol.io) 服务器，暴露 [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/) 集群操作为工具，使用官方 [go-sdk](https://github.com/modelcontextprotocol/go-sdk) 以 Go 构建。工具响应为紧凑的 JSON（无缩进）以最小化令牌使用。
## 工具
### 集群和节点
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_nodes` | 列出集群中的所有节点 | — |
| `get_node_status` | 节点的详细状态 | `node` |
| `list_cluster_resources` | 集群中的所有资源 | `type`（可选：`vm`、`storage`、`node`、`sdn`） |
| `get_cluster_status` | 集群状态和法定人数信息 | — |
| `list_node_storage` | 节点上可用的存储池 | `node` |
| `list_node_tasks` | 节点上的近期任务 | `node`、`limit`（可选） |
| `get_node_disks` | 节点上检测到的物理磁盘 | `node` |
### QEMU 虚拟机
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_vms` | 节点上的 QEMU 虚拟机 | `node` |
| `get_vm_status` | 虚拟机的状态和当前配置 | `node`、`vmid` |
| `get_vm_config` | 虚拟机的完整配置 | `node`、`vmid` |
| `start_vm` | 启动虚拟机（返回任务 UPID） | `node`、`vmid` |
| `stop_vm` | 硬停止虚拟机（返回任务 UPID） | `node`、`vmid` |
| `shutdown_vm` | 优雅的 ACPI 关闭（返回任务 UPID） | `node`、`vmid` |
| `reboot_vm` | 重启虚拟机（返回任务 UPID） | `node`、`vmid` |
| `suspend_vm` | 挂起虚拟机（返回任务 UPID） | `node`、`vmid` |
| `resume_vm` | 恢复挂起的虚拟机（返回任务 UPID） | `node`、`vmid` |
| `list_vm_snapshots` | 列出虚拟机的所有快照 | `node`、`vmid` |
| `create_vm_snapshot` | 创建虚拟机快照（返回任务 UPID） | `node`、`vmid`、`snapname`、`description`（可选） |
| `rollback_vm_snapshot` | 将虚拟机回滚到快照（返回任务 UPID） | `node`、`vmid`、`snapname` |
| `delete_vm_snapshot` | 删除虚拟机快照（返回任务 UPID） | `node`、`vmid`、`snapname` |
| `create_vm` | 创建新的 QEMU 虚拟机（返回任务 UPID） | `node`、`vmid`、`name`（可选）、`memory`（可选）、`cores`（可选）、`iso`（可选）、`disk`（可选）、`net0`（可选）、`start`（可选） |
| `clone_vm` | 克隆虚拟机到新的 ID（返回任务 UPID） | `node`、`vmid`、`newid`、`name`（可选）、`target_node`（可选） |
| `set_vm_config` | 更新虚拟机配置（同步，无任务） | `node`、`vmid`、`name`（可选）、`memory`（可选）、`cores`（可选）、`onboot`（可选）、`description`（可选） |
| `resize_vm_disk` | 调整虚拟机磁盘大小（返回任务 UPID） | `node`、`vmid`、`disk`（例如 `scsi0`）、`size`（例如 `+10G` 或 `50G`） |
| `migrate_vm` | 将虚拟机迁移到另一个节点（返回任务 UPID） | `node`、`vmid`、`target`、`online`（可选，实时迁移） |
| `restore_vm` | 从 vzdump 备份存档恢复虚拟机（返回任务 UPID） | `node`、`vmid`、`archive`（volid）、`storage`（可选）、`start`（可选） |
| `move_vm_disk` | 将虚拟机磁盘移动到不同的存储池（返回任务 UPID） | `node`、`vmid`、`disk`（例如 `scsi0`）、`storage`（目标池）、`delete_source`（可选） |
### LXC 容器
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_containers` | 节点上的 LXC 容器 | `node` |
| `get_container_status` | 容器的状态 | `node`、`vmid` |
| `get_container_config` | 容器的完整配置 | `node`、`vmid` |
| `start_container` | 启动容器（返回任务 UPID） | `node`、`vmid` |
| `stop_container` | 停止容器（返回任务 UPID） | `node`、`vmid` |
| `shutdown_container` | 优雅的 ACPI 关闭（返回任务 UPID） | `node`、`vmid` |
| `reboot_container` | 重启容器（返回任务 UPID） | `node`、`vmid` |
| `list_container_snapshots` | 列出容器的所有快照 | `node`、`vmid` |
| `create_container_snapshot` | 创建容器快照（返回任务 UPID） | `node`、`vmid`、`snapname`、`description`（可选） |
| `rollback_container_snapshot` | 将容器回滚到快照（返回任务 UPID） | `node`、`vmid`、`snapname` |
| `delete_container_snapshot` | 删除容器快照（返回任务 UPID） | `node`、`vmid`、`snapname` |
| `create_container` | 创建新的 LXC 容器（返回任务 UPID） | `node`、`vmid`、`ostemplate`、`hostname`（可选）、`memory`（可选）、`rootfs`（可选）、`password`（可选）、`net0`（可选）、`start`（可选） |
| `clone_container` | 克隆容器到新的 ID（返回任务 UPID） | `node`、`vmid`、`newid`、`hostname`（可选）、`target_node`（可选） |
| `set_container_config` | 更新容器配置（同步，无任务） | `node`、`vmid`、`hostname`（可选）、`memory`（可选）、`swap`（可选）、`onboot`（可选）、`description`（可选） |
| `resize_container_disk` | 调整容器磁盘大小（返回任务 UPID） | `node`、`vmid`、`disk`（例如 `rootfs`）、`size`（例如 `+5G` 或 `10G`） |
| `migrate_container` | 将容器迁移到另一个节点（返回任务 UPID） | `node`、`vmid`、`target`、`restart`（可选，停止+迁移+启动） |
| `restore_container` | 从 vzdump 备份存档恢复容器（返回任务 UPID） | `node`、`vmid`、`archive`（volid）、`storage`（可选）、`hostname`（可选）、`start`（可选） |
### 备份
| 工具 | 描述 | 参数 |
|---|---|---|
| `create_backup` | 创建虚拟机或容器的 vzdump 备份（返回任务 UPID） | `node`、`vmid`、`storage`（可选）、`mode`（可选：`snapshot`\|`suspend`\|`stop`，默认为 `snapshot`）、`compress`（可选：`zstd`\|`gzip`\|`lzo`\|`0`，默认为 `zstd`） |
| `list_backups` | 列出存储池中的所有备份卷 | `node`、`storage` |
### 任务
| 工具 | 描述 | 参数 |
|---|---|---|
| `get_task_status` | 轮询异步任务的状态 | `node`、`upid` |
### 网络
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_node_network` | 列出节点上的网络接口 | `node`、`type`（可选：`bridge`、`bond`、`eth`、`alias`、`vlan`、`OVSBridge`、`OVSBond`、`OVSPort`、`OVSIntPort`、`any_bridge`） |
| `get_node_network_interface` | 获取特定网络接口的配置 | `node`、`iface`（例如 `vmbr0`） |
| `create_node_network_interface` | 在节点上创建新的网络接口（暂存直到 `apply_node_network_changes`） | `node`、`iface`、`type`（`bridge`\|`bond`\|`eth`\|`alias`\|`vlan`\|`OVSBridge`\|`OVSBond`\|`OVSPort`\|`OVSIntPort`）、`address`（可选，点分十进制或 CIDR）、`netmask`（可选）、`gateway`（可选）、`address6`（可选，CIDR）、`gateway6`（可选）、`mtu`（可选）、`autostart`（可选，`1`=启动，`0`=手动）、`bridge_ports`（可选）、`bridge_stp`（可选）、`bridge_fd`（可选）、`bond_mode`（可选）、`slaves`（可选）、`comments`（可选） |
| `update_node_network_interface` | 更新节点上现有的网络接口（暂存直到 `apply_node_network_changes`） | `node`、`iface`、`type`（必需：与 `create_node_network_interface` 相同的值），以及 `create_node_network_interface` 中的任何可选字段 |
| `apply_node_network_changes` | 应用节点上的所有暂存网络配置更改，重新加载网络栈 | `node` |
### 防火墙
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_cluster_firewall_rules` | 列出数据中心级别的所有防火墙规则 | — |
| `get_cluster_firewall_options` | 获取数据中心防火墙策略选项（默认进/出策略，日志记录） | — |
| `list_vm_firewall_rules` | 列出 QEMU 虚拟机的所有防火墙规则 | `node`、`vmid` |
| `get_vm_firewall_options` | 获取 QEMU 虚拟机的防火墙策略选项 | `node`、`vmid` |
| `list_container_firewall_rules` | 列出 LXC 容器的所有防火墙规则 | `node`、`vmid` |
| `get_container_firewall_options` | 获取 LXC 容器的防火墙策略选项 | `node`、`vmid` |
| `add_vm_firewall_rule` | 向 QEMU 虚拟机添加防火墙规则 | `node`、`vmid`、`type`（`in`\|`out`）、`action`（`ACCEPT`\|`DROP`\|`REJECT`）、`proto`（可选）、`dport`（可选）、`sport`（可选）、`source`（可选）、`dest`（可选）、`iface`（可选）、`comment`（可选）、`enable`（可选） |
| `delete_vm_firewall_rule` | 按位置删除 QEMU 虚拟机的防火墙规则 | `node`、`vmid`、`pos`（从 0 开始） |
| `add_container_firewall_rule` | 向 LXC 容器添加防火墙规则 | `node`、`vmid`、`type`、`action`、`proto`（可选）、`dport`（可选）、`sport`（可选）、`source`（可选）、`dest`（可选）、`iface`（可选）、`comment`（可选）、`enable`（可选） |
| `delete_container_firewall_rule` | 按位置删除 LXC 容器的防火墙规则 | `node`、`vmid`、`pos`（从 0 开始） |
### 池管理
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_pools` | 列出集群中的所有资源池 | — |
| `get_pool` | 获取池的完整详细信息，包括其成员虚拟机、容器和存储 | `poolid` |
| `create_pool` | 创建新的资源池 | `poolid`、`comment`（可选） |
| `update_pool` | 更新池：更改注释或添加/删除成员虚拟机和存储 | `poolid`、`comment`（可选）、`vms`（可选，逗号分隔的 VM/CT ID）、`storage`（可选，逗号分隔的存储名称）、`delete`（可选，设置为 `true` 以删除列出的成员而不是添加） |
### 存储内容
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_storage_content` | 列出存储池中的卷 | `node`、`storage`、`content`（可选：`iso`、`vztmpl`、`backup`、`images`) |
| `get_storage_content_info` | 特定卷的详细信息 | `node`、`storage`、`volume`（完整的 volid，例如 `local:iso/debian.iso`) |
### 存储定义
| 工具 | 描述 | 参数 |
|---|---|---|
| `list_storages` | 列出集群范围的所有存储定义 | `type`（可选过滤：`nfs`、`pbs`、`dir`、`cifs`、`zfspool`等） |
| `get_storage` | 获取存储定义的完整配置 | `storage`（名称） |
| `add_storage` | 将新的存储目标添加到集群 | `storage`（名称）、`type`（必需：`nfs`\|`pbs`\|`dir`\|`cifs`\|`zfspool`...）、`server`（可选）、`export`（可选，NFS 路径）、`path`（可选，dir 路径）、`datastore`（可选，PBS 数据存储）、`username`（可选）、`password`（可选）、`fingerprint`（可选，PBS TLS 指纹）、`content`（可选，例如 `backup,images`）、`nodes`（可选，逗号分隔）、`shared`（可选，布尔值） |
| `update_storage` | 更新现有的存储定义 | `storage`（名称），以及：`server`、`export`、`path`、`datastore`、`username`、`password`、`fingerprint`、`content`、`nodes`、`shared` |
### 销毁（需光入）
这些工具 **默认不注册**。设置 `PROXMOX_ALLOW_DESTRUCTIVE=true` 启用它们。
| 工具 | 描述 | 参数 |
|---|---|---|
| `delete_vm` | 永久删除已停止的 QEMU 虚拟机（返回任务 UPID） | `node`、`vmid`、`confirmed`（必须为 `true`）、`purge`（可选） |
| `delete_container` | 永久删除已停止的 LXC 容器（返回任务 UPID） | `node`、`vmid`、`confirmed`（必须为 `true`）、`purge`（可选） |
| `delete_storage_content` | 永久删除存储池中的卷（返回任务 UPID） | `node`、`storage`、`volume`（完整的 volid，例如 `local:iso/debian.iso`)` |
| `reboot_node` | 重启整个 Proxmox 节点 | `node`、`confirmed`（必须为 `true`） |
| `shutdown_node` | 关闭整个 Proxmox 节点 | `node`、`confirmed`（必须为 `true`） |
| `delete_pool` | 永久删除一个空资源池 | `poolid`、`confirmed`（必须为 `true`） |
| `remove_storage` | 从集群中删除存储定义（不会影响底层数据） | `storage`（名称）、`confirmed`（必须为 `true`） |
| `delete_node_network_interface` | 从节点中删除网络接口（暂存直到 `apply_node_network_changes`） | `node`、`iface`、`confirmed`（必须为 `true`） |
生命周期和快照操作为非阻塞操作 - 它们立即返回异步任务的 UPID。使用 `get_task_status` 轮询完成。
## 安装
### 下载预构建二进制文件
在 [Releases](https://github.com/gordcurrie/proxmox-mcp/releases) 页面上下载适用于您平台的最新版本。
| 平台 | 二进制文件 |
|---|---|
| Linux（amd64） | `proxmox-mcp_linux_amd64` |
| Linux（arm64） | `proxmox-mcp_linux_arm64` |
| macOS（amd64） | `proxmox-mcp_darwin_amd64` |
| macOS（arm64） | `proxmox-mcp_darwin_arm64` |
| Windows（amd64） | `proxmox-mcp_windows_amd64.exe` |
使其可执行并将其放在您的 `PATH` 上（替换为您的平台的文件名）：
```bash
chmod +x <binary-name>
mv <binary-name> /usr/local/bin/proxmox-mcp
```
> Windows 用户：重命名 `.exe` 并将其添加到您的 `%PATH%` 目录中。
### 从源代码构建
需要 Go 1.26+。您还需要一个 Proxmox VE API 令牌 - 在 **Datacenter → Permissions → API Tokens** 中创建一个。
```bash
git clone https://github.com/gordcurrie/proxmox-mcp
cd proxmox-mcp
cp .env.example .env # 复制示例 env 文件
$EDITOR .env # 设置 PROXMOX_* 值（参见下表）
make build # 二进制文件位于 bin/proxmox-mcp
```
## 配置
所有配置均通过环境变量进行：
| 变量 | 是否必需 | 描述 |
|---|---|---|
| `PROXMOX_API_URL` | 是 | 例如 `https://pve:8006/api2/json` |
| `PROXMOX_TOKEN_ID` | 是 | 例如 `root@pam!mcp` |
| `PROXMOX_TOKEN_SECRET` | 是 | 令牌 UUID 密钥 |
| `PROXMOX_INSECURE` | 否 | `true` 跳过 TLS 验证（自签名证书） |
| `PROXMOX_ALLOW_DESTRUCTIVE` | 否 | `true` 注册 `delete_vm`、`delete_container`、`delete_storage_content`、`reboot_node`、`shutdown_node` 和 `delete_pool` 工具（默认：禁用） |
在运行前导入您的 `.env` 文件：
```bash
set -a && source .env && set +a
```
## 运行
### stdio（默认 - 用于本地 MCP 客户端）
```bash
./bin/proxmox-mcp
```
### HTTP（可流式传输 - 用于远程/共享部署）
```bash
./bin/proxmox-mcp --transport http --addr localhost:8080
```
## VS Code Copilot 配置
在工作区中创建 `.vscode/mcp.json`（已在 gitignore 中）：
```json
{
"servers": {
"proxmox-mcp": {
"type": "stdio",
"command": "/path/to/proxmox-mcp/bin/proxmox-mcp",
"env": {
"PROXMOX_API_URL": "https://your-proxmox-host:8006/api2/json",
"PROXMOX_TOKEN_ID": "user@realm!tokenid",
"PROXMOX_TOKEN_SECRET": "your-token-secret"
}
}
}
}
```
然后打开 Copilot 聊天面板，切换到 **Agent** 模式，`proxmox-mcp` 服务器将出现在可用工具中。
## Claude Desktop 配置
将服务器添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"proxmox-mcp": {
"command": "/path/to/proxmox-mcp/bin/proxmox-mcp",
"env": {
"PROXMOX_API_URL": "https://your-proxmox-host:8006/api2/json",
"PROXMOX_TOKEN_ID": "user@realm!tokenid",
"PROXMOX_TOKEN_SECRET": "your-token-secret"
}
}
}
}
```
保存配置后重启 Claude Desktop - Proxmox 工具将出现在工具选择器中。
## OpenCode 配置
将服务器添加到项目根目录的 `opencode.json`（或全局配置的 `~/.config/opencode/opencode.json`）中：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"proxmox-mcp": {
"type": "local",
"command": ["/path/to/proxmox-mcp/bin/proxmox-mcp"],
"enabled": true,
"environment": {
"PROXMOX_API_URL": "https://your-proxmox-host:8006/api2/json",
"PROXMOX_TOKEN_ID": "user@realm!tokenid",
"PROXMOX_TOKEN_SECRET": "your-token-secret"
}
}
}
}
```
## 开发
```bash
make install-tools # 安装 golangci-lint、gosec、govulncheck、gofumpt
make check # 完整的质量门控：修复、格式化、检查、lint、sec、vulncheck、测试、构建
make test # 仅测试（启用竞争检测器）
make build # 仅构建 → bin/proxmox-mcp
make clean # 删除 bin/proxmox-mcp
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器