内容
<h1 align="center">proxmox-mcp</h1>
<p align="center">
<strong>一款允许AI客户端通过简单的API令牌身份验证读取和操作Proxmox VE集群、虚拟机、容器和节点的MCP服务器。</strong>
</p>
<p align="center">
原因：您的家庭实验室运行在Proxmox上，您希望一个代理能够清点、启动一个虚拟机或跟踪一个任务，而无需您点击Web UI。它的不同之处在于：一个严格的三层写入门控机制被内置到每个工具中，因此读取是开放的，但任何更改状态的操作都需要一个明确的确认标志，而任何破坏性操作都需要在此基础上再加两个门控。<strong>状态：工作中。</strong> 工具表面和安全模型是稳定的，但该软件包仍处于1.0版本之前，最新发布的版本是<code>0.3.0</code>。
</p>
<p align="center">
<img src="https://img.shields.io/npm/v/@solomonneas/proxmox-mcp?style=for-the-badge&label=npm" alt="npm版本">
<img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/proxmox-mcp/ci.yml?branch=master&style=for-the-badge&label=CI状态" alt="CI状态">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT许可证">
<img src="https://img.shields.io/badge/MCP-server-7c3aed?style=for-the-badge" alt="MCP服务器">
</p>
<p align="center">
<a href="https://lidless.dev/proxmox-mcp"><strong>网站和文档→ lidless.dev/proxmox-mcp</strong></a>
</p>
## 它做什么
proxmox-mcp是一个开源的[模型上下文协议](https://modelcontextprotocol.io)服务器，用于[Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview)，这是一个开源的虚拟化平台。它为AI客户端（Claude Desktop、Claude Code、OpenClaw、Codex CLI或任何MCP主机）提供了一个结构化、受控的接口到Proxmox集群：清点虚拟机和LXC容器、检查节点和存储状态、读取RRD指标、跟踪任务、管理快照和备份、在虚拟机中运行有门控的读取和shell命令，并预置、克隆或销毁资源，所有这些都通过Proxmox API令牌身份验证。
它是为家庭实验室和虚拟化操作员设计的，他们希望指向他们的集群一个代理，而不给它一个根shell。区别在于安全模型：42个工具分布在四个层级中，其中读取不需要任何标志，安全写入需要`confirm: true`，而破坏性操作需要`confirm: true` + `destructive: true` + 一个进程级的`PROXMOX_ENABLE_DESTRUCTIVE=1`环境标志。一个幻觉或粗心的工具调用失败关闭，在任何HTTP流量到达Proxmox之前。
## 证明
一个真实的MCP客户端配置。将其放入Claude Desktop（`claude_desktop_config.json`）中，42个工具就会出现在客户端。读取立即生效；破坏性环境门控在您选择加入之前保持关闭。
```json
{
"mcpServers": {
"proxmox": {
"command": "npx",
"args": ["-y", "@solomonneas/proxmox-mcp"],
"env": {
"PROXMOX_URL": "https://192.0.2.10:8006",
"PROXMOX_TOKEN_ID": "pve-admin@pam!api-token-1",
"PROXMOX_TOKEN_SECRET": "00000000-0000-0000-0000-000000000000",
"PROXMOX_TLS_INSECURE": "false"
}
}
}
}
```
### 工具列表（42个工具，已针对源代码验证）
层级标记是权威的：每个工具的门控在代码中强制执行（`src/gates.ts` + 每个工具的模式），并且`WriteGateError`在门控不满足时在任何HTTP调用之前触发。
| 工具 | 层级 | 备注 |
| --- | --- | --- |
| `proxmox_status` | 1 读取 | 集群 + 节点状态。 |
| `proxmox_list_containers` | 1 读取 | 所有节点上的LXC库存。 |
| `proxmox_list_vms` | 1 读取 | 所有节点上的QEMU库存。 |
| `proxmox_get_resource` | 1 读取 | 通过vmid的单个容器或虚拟机配置 + 状态。 |
| `proxmox_get_vm_config` | 1 读取 | 通过vmid的QEMU虚拟机配置。 |
| `proxmox_get_container_config` | 1 读取 | 通过vmid的LXC容器配置。 |
| `proxmox_validate_qemu_smoke_source` | 1 读取 | 在实时烟雾克隆之前预检查QEMU虚拟机。 |
| `proxmox_audit_permissions` | 1 读取 | 检查与烟雾相关的路径的有效权限。 |
| `proxmox_recent_tasks` | 1 读取 | 每个节点的最近UPID任务列表。 |
| `proxmox_list_backups` | 1 读取 | 按存储的备份库存。 |
| `proxmox_resource_usage` | 1 读取 | CPU/内存/磁盘RRD指标。 |
| `proxmox_list_templates` | 1 读取 | 可用于克隆 + 容器创建的LXC + 虚拟机模板。 |
| `proxmox_list_storage` | 1 读取 | 一个节点或所有节点上的存储状态。 |
| `proxmox_list_snapshots` | 1 读取 | 一个LXC或虚拟机的快照库存。 |
| `proxmox_guest_network` | 1 读取 | 虚拟机的网络接口和可用的IPv4地址。 |
| `proxmox_wait_task` | 1 读取 | 轮询UPID直到停止或超时。 |
| `proxmox_next_vmid` | 1 读取 | 获取下一个可用的VMID用于预置。 |
| `proxmox_list_pool_resources` | 1 读取 | 检查分配给Proxmox池的资源，默认为`mcp-smoke`。 |
| `proxmox_get_task_status` | 1 读取 | 单个UPID状态查找。 |
| `proxmox_get_task_log` | 1 读取 | UPID的任务日志尾部。 |
| `proxmox_read_file` | 2 有门控的虚拟机读取 | 从LXC或QEMU虚拟机内部读取文件（SSH + `cat`）。需要`confirm: true`。 |
| `proxmox_stat_path` | 2 有门控的虚拟机读取 | 检查虚拟机路径元数据。需要`confirm: true`。 |
| `proxmox_list_directory` | 2 有门控的虚拟机读取 | 列出一个虚拟机目录。需要`confirm: true`。 |
| `proxmox_service_status` | 2 有门控的虚拟机读取 | 读取虚拟机内的systemd服务状态。需要`confirm: true`。 |
| `proxmox_start_resource` | 2 安全写入 | 启动容器或虚拟机。需要`confirm: true`。 |
| `proxmox_stop_resource` | 2 安全写入 | 正常关闭。需要`confirm: true`。 |
| `proxmox_reboot_resource` | 2 安全写入 | 原地重启。需要`confirm: true`。 |
| `proxmox_snapshot_resource` | 2 安全写入 | 创建命名快照。需要`confirm: true`。 |
| `proxmox_run_backup` | 2 安全写入 | 触发vmid的vzdump。需要`confirm: true`。 |
| `proxmox_create_container` | 2 安全写入 | 从模板预置新的LXC（`POST /nodes/{node}/lxc`）。需要`confirm: true`。 |
| `proxmox_create_vm` | 2 安全写入 | 从模板预置新的QEMU虚拟机（`POST /nodes/{node}/qemu`）。需要`confirm: true`。 |
| `proxmox_clone_resource` | 2 安全写入 | 克隆现有的容器或虚拟机到新的vmid。需要`confirm: true`。 |
| `proxmox_exec` | 2 安全写入 | 在LXC或QEMU虚拟机内运行shell命令。返回stdout/stderr/exit_code。需要`confirm: true`。 |
| `proxmox_write_file` | 2 安全写入 | 在LXC或QEMU虚拟机内写入文本文件。需要`confirm: true`。 |
| `proxmox_service_start` | 2 安全写入 | 启动虚拟机内的systemd服务。需要`confirm: true`。 |
| `proxmox_service_stop` | 2 安全写入 | 停止虚拟机内的systemd服务。需要`confirm: true`。 |
| `proxmox_service_restart` | 2 安全写入 | 重启虚拟机内的systemd服务。需要`confirm: true`。 |
| `proxmox_rollback_snapshot` | 3 破坏性 | 回滚资源到命名快照。 |
| `proxmox_destroy_resource` | 3 破坏性 | 永久删除LXC或虚拟机（`DELETE /nodes/{node}/{type}/{vmid}`）。 |
| `proxmox_cleanup_smoke_resources` | 3 破坏性 | 从烟雾池中删除烟雾前缀的LXC/QEMU虚拟机。 |
| `proxmox_delete_snapshot` | 3 破坏性 | 删除命名快照。 |
| `proxmox_force_stop_resource` | 3 破坏性 | 非正常硬停止运行的容器或虚拟机。 |
**读取（20）：** 开放；不需要标志。
**有门控的虚拟机读取（4）：** 虚拟机文件/路径/目录/服务检查工具需要`confirm: true`，因为它们通过主机支持的SSH暴露虚拟机内部状态。
**安全写入（13）：** 需要`confirm: true`。模式文档在每个工具上都有门控。`WriteGateError`在任何HTTP调用之前触发。
**破坏性（5）：** 需要`confirm: true` + `destructive: true` + 环境变量`PROXMOX_ENABLE_DESTRUCTIVE=1`。所有三个门控必须满足；如果任何一个缺失，工具会抛出`WriteGateError`，在解析资源之前。
> 五个工具是破坏性的，可以删除或硬停止虚拟机：`proxmox_destroy_resource`、`proxmox_cleanup_smoke_resources`、`proxmox_rollback_snapshot`、`proxmox_delete_snapshot`和`proxmox_force_stop_resource`。它们在`PROXMOX_ENABLE_DESTRUCTIVE=1`进程环境标志后面，并且在不设置时保持惰性。参见[SECURITY.md](SECURITY.md)和[安全](#安全)部分。
## 快速开始
全局安装或按需使用`npx`安装：
```bash
npm install -g @solomonneas/proxmox-mcp
# 或，无需安装：
npx -y @solomonneas/proxmox-mcp
```
设置三个必需的凭证环境变量（擦除共享配置中的真实主机和IP地址）：
```bash
export PROXMOX_URL=https://192.0.2.10:8006
export PROXMOX_TOKEN_ID=pve-admin@pam!api-token-1
export PROXMOX_TOKEN_SECRET=00000000-0000-0000-0000-000000000000
# 可选：跳过TLS证书验证，用于家庭实验室自签名证书。
# 接受true/1/yes（不区分大小写）。默认为false。
export PROXMOX_TLS_INSECURE=false
```
将其连接到您的MCP客户端（完整的客户端配置见[设置](#设置)）：
```bash
# Claude Code
claude mcp add proxmox -s user -- npx -y @solomonneas/proxmox-mcp
```
然后询问您的代理列出集群的容器。读取操作仅需三个凭证变量；写入和破坏性层级在您选择加入之前保持门控。
> 注意：发布到npm的最新版本是`0.3.0`。此仓库跟踪npm版本；安装固定发布版本。
## 为什么不使用替代方案？
- **Proxmox Web UI** 是规范控制平面，您应该保留它。proxmox-mcp不是替代品；它是代理面向的读取/操作表面，以便AI客户端可以在其已经运行的循环中清点、跟踪和操作集群，而无需您驱动浏览器。
- **在您的代理中编写Proxmox API调用** 有效，但代理必须自己管理令牌身份验证、红actor、重试、任务轮询和（关键）安全性。proxmox-mcp提供令牌红actor、结构化MCP错误负载和三层写入门控，以便粗心的幻觉调用失败关闭。
- **通用"运行任何HTTP请求"的MCP工具** 提供给模型对Proxmox API的无边界访问，没有防护栏。proxmox-mcp是相反的：固定的命名工具表面，每个状态更改都有限制，每个破坏性操作都需要显式进程级环境标志。
- **Terraform / Ansible / `pct` + `qm`** 是用于声明式、审查、可重复的基础设施工具。proxmox-mcp用于交互式、代理驱动的检查和操作，而不是编纂您的集群。
## 什么是proxmox-mcp不是
- **不是用于破坏性操作的盲目自动化操作。** 破坏性层级存在于有意监督的工作（烟雾测试循环、故意销毁），而不是无人值守的代理。`PROXMOX_ENABLE_DESTRUCTIVE=1`标志是一个粗糙的“我正在积极进行此操作”的切换。保持未设置日常。
- **不是Proxmox集群管理器或编排器。** 它不调度、不运行在后台，也不保留任何自己的状态。它将MCP工具调用转换为Proxmox API调用和SSH命令，仅此而已。
- **不是最不特权令牌的替代品。** 写入门控是对行为不佳的模型的防护栏，而不是对Proxmox API令牌的替代品。从读取开始并升级到写权限。参见[SECURITY.md](SECURITY.md)。
- **还不稳定。| **它不是一个Proxmox集群管理器或编排器。** 它不调度、不运行后台任务，也不维护任何自己的状态。它将MCP工具调用转换为Proxmox API调用和SSH命令，仅此而已。
- **不是低权限令牌的替代品。** 写入门控是针对行为不佳的模型的防护栏，而不是Proxmox API令牌的替代品。从读取开始并升级到写入权限。参见[SECURITY.md](SECURITY.md)。
- **还不稳定。** 它是工作中、pre-1.0版本，工具表面可能在小版本之间发生变化。
## 配置
设置以下环境变量。所有三个凭证变量都是必需的。
```
PROXMOX_URL=https://192.0.2.10:8006
PROXMOX_TOKEN_ID=pve-admin@pam!api-token-1
PROXMOX_TOKEN_SECRET=00000000-0000-0000-0000-000000000000
# 可选：跳过TLS证书验证（家庭实验室自签名证书）。
# 接受true/1/yes（不区分大小写）。默认为false。
PROXMOX_TLS_INSECURE=false
```
`PROXMOX_URL`后面的斜杠会被剥离。令牌秘密会在启动时注册到红actor中，并从所有日志和错误输出中屏蔽。
### 容器内执行环境变量
`proxmox_exec`、`proxmox_read_file`和`proxmox_write_file`工具通过SSH连接到Proxmox主机（对于LXC，通过`pct exec`）或直接连接到VM（对于QEMU）。所有变量均为可选；默认值源自`PROXMOX_URL`。
| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `PROXMOX_SSH_HOST` | `PROXMOX_URL`中的主机名 | Proxmox主机用于`pct exec` |
| `PROXMOX_SSH_PORT` | `22` | SSH端口 |
| `PROXMOX_SSH_USER` | `root` | Proxmox主机上的SSH用户 |
| `PROXMOX_SSH_KEY` | `~/.ssh/id_ed25519` | Proxmox主机SSH密钥路径 |
| `PROXMOX_VM_SSH_USER` | 继承自`PROXMOX_SSH_USER` | 直接VM SSH的默认用户 |
| `PROXMOX_VM_SSH_KEY` | 继承自`PROXMOX_SSH_KEY` | 直接VM SSH的默认密钥 |
| `PROXMOX_SSH_MAX_OUTPUT_BYTES` | `1048576` | 每个SSH命令捕获的最大stdout字节数和最大stderr字节数 |
每台虚拟机覆盖（在执行时读取，无需重启MCP）：
- `PROXMOX_VM_<vmid>_SSH_HOST` - 固定VM的IP（绕过代理）
- `PROXMOX_VM_<vmid>_SSH_USER` - 每VM用户覆盖
- `PROXMOX_VM_<vmid>_SSH_KEY` - 每VM密钥覆盖
对于没有每VM环境变量覆盖的QEMU虚拟机，请在VM中安装`qemu-guest-agent`并使用`qm set <vmid> --agent 1`启用它，以便自动发现IP。
## 设置
### Claude Desktop
`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"proxmox": {
"command": "npx",
"args": ["-y", "@solomonneas/proxmox-mcp"],
"env": {
"PROXMOX_URL": "https://192.0.2.10:8006",
"PROXMOX_TOKEN_ID": "pve-admin@pam!api-token-1",
"PROXMOX_TOKEN_SECRET": "00000000-0000-0000-0000-000000000000",
"PROXMOX_TLS_INSECURE": "false"
}
}
}
}
```
### Claude Code
```bash
claude mcp add proxmox -s user -- npx -y @solomonneas/proxmox-mcp
```
然后在shell中导出环境变量（`~/.bashrc`，`~/.zshrc`）或传递`--env`标志。
### OpenClaw
插件加载后自动运行。配置位于您的`~/.openclaw/openclaw.json` `plugins.entries.proxmox`（或使用捆绑的`openclaw.plugin.json`）：
```json
{
"plugins": {
"entries": {
"proxmox": {
"package": "@solomonneas/proxmox-mcp",
"activation": { "onStartup": true }
}
}
}
}
```
环境变量从`~/.openclaw/workspace/.env`继承到插件。
### Codex CLI
`~/.codex/config.toml`:
```toml
[mcp_servers.proxmox]
command = "npx"
args = ["-y", "@solomonneas/proxmox-mcp"]
[mcp_servers.proxmox.env]
PROXMOX_URL = "https://192.0.2.10:8006"
PROXMOX_TOKEN_ID = "pve-admin@pam!api-token-1"
PROXMOX_TOKEN_SECRET = "00000000-0000-0000-0000-000000000000"
PROXMOX_TLS_INSECURE = "false"
```
## 安全
此MCP使用三层写入门控模型。层级在代码中强制执行，而不是仅在文档中描述。
- **层级 1（读取）：** 开放。不需要确认标志。
- **层级 2（虚拟机有门控的读取 + 安全写入）：** 需要显式`confirm: true`参数。虚拟机内部文件/路径/目录/服务检查、安全写入、创建容器、创建虚拟机、克隆、`exec`、`write_file`和虚拟机服务启动/停止/重启位于此处。工具调用如果没有确认标志，则会抛出`WriteGateError`，在任何HTTP流量之前。
- **层级 3（破坏性）：** 需要`confirm: true` + `destructive: true` + 环境标志`PROXMOX_ENABLE_DESTRUCTIVE=1`。永久资源删除、烟雾池清理、快照回滚/删除和非正常强制停止位于此处。
### 破坏性操作的环境门控
三级破坏性工具（`proxmox_destroy_resource`、`proxmox_cleanup_smoke_resources`、`proxmox_rollback_snapshot`、`proxmox_delete_snapshot`、`proxmox_force_stop_resource`）需要一个额外的安全门控，除了每个工具的`confirm: true` + `destructive: true`参数之外：`PROXMOX_ENABLE_DESTRUCTIVE=1`环境变量必须在MCP进程上设置。没有它，工具会在任何HTTP调用之前抛出`WriteGateError`。`proxmox_cleanup_smoke_resources`默认为`dry_run: true`，在破坏性环境门控之前预览目标。
这是故意的：破坏性操作很少见。环境标志是一个粗糙的“我正在主动进行烟雾测试循环”的切换开关。在大多数情况下保持未设置；仅在主动销毁资源作为工作流程的一部分时才启用。
**API令牌范围推荐：** 从只读令牌（PVE `Datastore.Audit` + `VM.Audit` + `Sys.Audit`）开始并验证读取工具端到端。升级到写入权限（`VM.PowerMgmt`、`VM.Snapshot`、`VM.Backup`）仅在您确认转录器正在屏蔽您的机密并且模型正在遵守确认门控后。令牌与PVE用户绑定，可以从Datacenter > Permissions > API Tokens立即撤销。
`PROXMOX_TLS_INSECURE=true`切换开关仅用于家庭实验室自签名证书。在具有真实CA签名证书的任何环境中，请将其设置为`false`。
完整的安保政策、报告和范围内的/范围外的详细信息见[SECURITY.md](SECURITY.md)。
## 现场烟雾测试
只读现场烟雾测试：
```bash
PROXMOX_ENABLE_LIVE_SMOKE=1 npm run smoke:live
```
完整的从头开始的 CT 生命周期烟雾测试需要一个可以创建、启动、停止、检查和销毁 `mcp-smoke` 池中资源的令牌：
```bash
PROXMOX_ENABLE_LIVE_SMOKE=1 \
PROXMOX_SMOKE_CREATE=1 \
PROXMOX_ENABLE_DESTRUCTIVE=1 \
npm run smoke:live
```
可选的从头开始的 CT 备份和快照回滚烟雾测试：
```bash
PROXMOX_ENABLE_LIVE_SMOKE=1 \
PROXMOX_SMOKE_CREATE=1 \
PROXMOX_SMOKE_BACKUP=1 \
PROXMOX_SMOKE_BACKUP_STORAGE=local \
PROXMOX_SMOKE_SNAPSHOT_ROLLBACK=1 \
PROXMOX_ENABLE_DESTRUCTIVE=1 \
npm run smoke:live
```
在 Proxmox 主机上创建限定范围的烟雾测试角色/用户/令牌：
```bash
PROXMOX_CREATE_SMOKE_TOKEN=1 bash scripts/create-smoke-token.sh
```
脚本创建或更新角色 `McpSmokeRole`，池 `mcp-smoke`，用户 `mcp-smoke@pve`，令牌 `mcp-smoke@pve!live-smoke`，以及烟雾测试池和 `local` 及 `local-lvm` 存储的 ACL。Proxmox 仅打印一次令牌密钥；请将其存储在您的私有环境中，不要提交。
Proxmox 还会在创建新的 CT/VM 之前检查 `/vms/<vmid>`。对于一次性烟雾测试，在运行生命周期烟雾测试之前授予确切的下一个 VMID：
```bash
PROXMOX_CREATE_SMOKE_TOKEN=1 PROXMOX_SMOKE_VMID_GRANT=102 bash scripts/create-smoke-token.sh
```
现在，`npm run smoke:live` 在 `PROXMOX_SSH_HOST`、`PROXMOX_SSH_USER` 和 `PROXMOX_SSH_KEY` 可用时，尝试在创建从头开始的 CT 或 QEMU 克隆之前自动授予确切的 VMID。设置 `PROXMOX_SMOKE_SKIP_AUTO_GRANT=1` 以禁用它。
可选的 QEMU 克隆烟雾测试：
```bash
PROXMOX_ENABLE_LIVE_SMOKE=1 \
PROXMOX_ENABLE_DESTRUCTIVE=1 \
PROXMOX_SMOKE_QEMU_SOURCE_VMID=9000 \
npm run smoke:live
```
这验证源，完整克隆到一个临时 VMID，启动它，等待 guest-agent 网络数据，停止它，然后销毁它。使用 `PROXMOX_SMOKE_QEMU_TARGET_VMID` 或 `PROXMOX_SMOKE_QEMU_NAME` 来覆盖生成的目标。
QEMU 源应该是一个小型停止的 VM 或模板，启用 `agent: enabled=1`，DHCP 网络，没有 PCI/USB 直通，没有原始 `args`，并且磁盘大小适中。首先检查它：
```bash
# tool: proxmox_validate_qemu_smoke_source { "vmid": 9000 }
```
审计烟雾测试令牌权限：
```bash
# tool: proxmox_audit_permissions {
# "userid": "mcp-smoke@pve!live-smoke",
# "source_vmid": 103,
# "target_vmid": 102
# }
```
可选的 systemd 服务烟雾测试：
```bash
PROXMOX_ENABLE_LIVE_SMOKE=1 \
PROXMOX_SMOKE_SYSTEMD_VMID=100 \
PROXMOX_SMOKE_SERVICE=basic.target \
npm run smoke:live
```
要运行实时服务操作以及状态，请添加 `PROXMOX_SMOKE_SERVICE_ACTION=start|stop|restart` 和 `PROXMOX_SMOKE_SERVICE_ACTION_CONFIRM=1`。
审计或清理残留的烟雾测试资源：
```bash
# 只读池审计
# tool: proxmox_list_pool_resources { "pool": "mcp-smoke" }
# 干燥运行清理，只针对池中名为 mcp-smoke-* 的资源
# tool: proxmox_cleanup_smoke_resources {}
# 实际清理等待删除任务，并跳过正在运行的 guest，除非 force:true
# tool: proxmox_cleanup_smoke_resources { "dry_run": false, "confirm": true, "destructive": true }
```
## 贡献
欢迎提交错误报告和补丁。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解容易实施的更改、本地开发以及每项更改必须遵守的安全规则。参与即表示您同意 [行为准则](CODE_OF_CONDUCT.md)。
## 更新日志
请参阅 [CHANGELOG.md](CHANGELOG.md) 获取发布历史。
## 许可证
MIT。请参阅 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器