proxmox-mcp-server

<div align="center"> <a href="https://soyrage.es/"> <img src="./assets/soyrage-banner.svg" alt="SoyRage Agency — 全栈开发工程师 × 基础设施工程师 · soyrage.es" width="100%"> </a> <br/> # 🖥️ Proxmox MCP 服务器 **与你的 Proxmox VE 集群聊天。** 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，可以将任何支持 MCP 的 AI（如 Claude Desktop、Cursor、Continue、Zed）变成 **Proxmox 虚拟环境** 的自然语言操作员：节点、QEMU 虚拟机、LXC 容器、存储、任务和快照。 *“列出我的虚拟机和哪些虚拟机已关闭。” · “`web`（虚拟机 ID 101）使用了多少 RAM？” · “在升级 `db` 之前创建快照。” · “温和地关闭容器 200。”* <br/> <img src="./assets/screenshots/tui-dashboard.png" alt="Proxmox MCP 服务器终端仪表盘，由 SoyRage Agency 提供 — 标签页、实时仪表盘、客机操作系统、快照和一键操作" width="88%"> _{💻 内置的 **`proxmox-mcp-tui`** 终端仪表盘 — 标签页视图（客机 · 节点 · 存储 · 任务）、实时 CPU/内存/磁盘仪表盘、客机 **操作系统**、搜索、快照和一键操作。 <a href="#-the-terminal-ui-tui">更多截图 ↓</a>} <br/><br/> [](https://github.com/soyrageagency/proxmox-mcp-server/actions/workflows/ci.yml) [](https://nodejs.org) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io) [](https://pve.proxmox.com/pve-docs/api-viewer/) [](./LICENSE) [](https://www.paypal.com/paypalme/soyrageagency) ### 由 **[SoyRage Agency](https://soyrage.es/)** 设计、构建和维护 · **https://soyrage.es/** **⚡ 新用户？一键安装 → [快速安装](#-quick-install-one-command)。** · **☕ [支持该项目](https://www.paypal.com/paypalme/soyrageagency)** </div> > 🐳 寻找 Docker 等价物？查看姊妹项目 **[docker-mcp-server](https://github.com/soyrageagency/docker-mcp-server)** — 相同的理念，适用于 Docker 和 Compose。 --- ## 📑 目录 - [快速安装（一键）](#-quick-install-one-command) - [这是什么？](#-what-is-this) - [功能概述](#-feature-overview) - [工作原理](#-how-it-works) - [需求](#-requirements) - [安装](#-installation) - [终端 UI（TUI）](#-the-terminal-ui-tui) - [创建 Proxmox API 令牌](#-create-a-proxmox-api-token) - [连接到你的 AI 客户端](#-connecting-to-your-ai-client) - [配置参考](#-configuration-reference) - [TLS 和自签名证书](#-tls--self-signed-certificates) - [安全模型和网络](#-security-model--networking) - [完整的工具参考](#-complete-tool-reference) - [示例对话](#-example-conversations) - [模块化插件架构](#-modular-plugin-architecture) - [项目结构](#-project-structure) - [开发](#-development) - [故障排除和常见问题](#-troubleshooting--faq) - [路线图](#-roadmap) - [支持该项目](#-support-the-project) - [致谢和许可证](#-credits--license) --- ## ⚡ 快速安装（一键） **以前从未做过？只有 3 个步骤，大约 3 分钟。** 您 **不需要** 触摸任何配置文件 — 一个友好的向导会询问您几个问题并设置所有内容。 #### ✅ 步骤 1 — 安装您需要的两个东西（一次） - [**Node.js**](https://nodejs.org/) （点击大绿色“LTS”按钮，接着下一步-下一步-完成）。 - [**Git**](https://git-scm.com/downloads)。 #### ✅ 步骤 2 — 运行一个命令 <table> <tr><td><b>🪟 Windows</b><br/>_PowerShell</td><td> ```powershell irm https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/install.ps1 | iex ``` </td></tr> <tr><td><b>🍎 macOS / 🐧 Linux</b><br/>_终端</td><td> ```bash curl -fsSL https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/install.sh | bash ``` </td></tr> </table> #### ✅ 步骤 3 — 复制粘贴您的详细信息，当向导询问时 就这样 — 向导会在一分钟内完成所有设置并为您**测试连接**： ```text 此向导在不到一分钟内设置所有内容。您需要： 1. 您的 Proxmox 网址（您登录的网址）。 2. API 令牌（最安全）— 或您的 Proxmox 用户名 + 密码。 Proxmox 地址（例如 https://192.168.1.10:8006）：https://10.0.0.11:8006 您有 API 令牌吗？（Y/n）：y 令牌 ID（user@realm!name，例如 root@pam!mcp）：root@pam!mcp 令牌密钥（粘贴 UUID）：•••••••-••••-••••-••••-•••••••••••• 验证 TLS 证书？（大多数 Proxmox 使用自签名 → 否）（y/N）：n 只读模式？（仅查看 — 最安全）（y/N）：n 测试连接… ✓ 连接到 Proxmox VE（8.2.4） ✓ 已将凭证保存到 .env ✓ 在您的 Claude 配置中添加了“proxmox”服务器。 完成！ → 重启 Claude Desktop 并询问“列出我的 Proxmox 虚拟机。” ``` **然后重启 Claude Desktop 并说：** *“列出我的 Proxmox 虚拟机和容器。”* 🎉 <details><summary><b>您还没有 API 令牌吗？（大约 20 秒创建）</b></summary> 在 Proxmox 网页界面：**数据中心 → 权限 → API 令牌 → 添加**，选择用户 `root@pam`，命名为 `mcp`，然后**复制密钥**（仅显示一次）。您的令牌 ID 为 `root@pam!mcp`。更多详细信息请参见 [创建 Proxmox API 令牌](#-create-a-proxmox-api-token)。如果您不想现在创建，向导也接受您的**用户名 + 密码**。 </details> <details><summary><b>已经克隆了存储库，或想重新运行设置？</b></summary> 运行 **`npm run setup`** 从项目文件夹。该安装程序**备份**并**合并**您的现有 Claude 配置，因此其他 MCP 服务器得以保留。 </details> <details><summary><b>没有 Proxmox 集群进行测试？</b></summary> 尝试 [**演示模式**](#-try-it-instantly--demo-mode-no-proxmox-needed) — 逼真的虚假数据，不需要主机。 </details> > 💙 如果这为您节省了时间，请 [**在 PayPal 上支持该项目**](https://www.paypal.com/paypalme/soyrageagency) 并给一个 ⭐。 --- ## 🧭 这是什么？ **模型上下文协议（MCP）** 是一个开放标准，允许 AI 助手通过定义良好的 JSON-RPC 接口与外部工具通信。**Proxmox MCP 服务器** 是一个 MCP *服务器*，它使用 **stdio** 协议进行通信，并将您的 [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment) 集群公开为一组安全、丰富描述的工具。 将任何支持 MCP 的助手指向它，您就可以用**普通语言**操作您的虚拟化堆栈 — 模型读取每个工具的模式，决定针对 Proxmox REST API 调用哪个工具，并将结果返回给您。为 **家庭实验室用户** 和 **系统管理员** 构建，他们更愿意询问而不是记住 `qm` 和 `pct` 标志。 --- ## 🚀 功能概述 | 领域 | 功能 | | --- | --- | | 🧭 **集群** | 列出带有负载的节点、节点状态、集群法定人数/成员资格以及整合的 `cluster_resources` 视图。 | | 🖥️ **虚拟机** | 列出 QEMU **虚拟机** 和 **LXC 容器**（按类型/运行筛选）、实时状态、完整配置和**虚拟机操作系统**（通过 QEMU 代理 — 名称、版本、IP）。 | | ⚙️ **生命周期** | 启动 · **关闭** · 硬 **停止** · 重启 · **挂起/恢复** — 用于虚拟机和容器。 | | 🚚 **管理** | **迁移** 到另一个节点 · **克隆**（从模板）· **调整** CPU/RAM · **删除**。 | | 📦 **备份** | **备份**（vzdump）· **列出存档** · **恢复** 到 VMID。 | | 🧱 **配置** | 列出模板/ISO · **创建** LXC 容器和 QEMU 虚拟机。 | | 📸 **快照** | 列出、**创建**（可选 RAM）、**回滚** 和 **删除** 快照。 | | 💾 **存储** | 列出每个节点存储类型、内容和使用情况。 | | 🧾 **任务** | 每个节点的最近任务日志（备份、迁移、操作...）。 | | ⌨️ **终端 UI** | 一个富有创意、专业的 [lazydocker](https://github.com/jesseduffield/lazydocker) 风格的仪表盘，用于您的集群，具有实时仪表盘、虚拟机操作系统和一键操作。 | | 🛡️ **安全** | 全局 **只读** 模式 · **虚拟机允许列表**（按 VMID 或名称）· TLS 验证控制。 | | 🔐 **身份验证** | API **令牌**（推荐）或用户名/密码 **票证** 身份验证。 | | 🧩 **模块化** | 每个功能都是一个可切换的**插件** — 暴露您想要的表面。 | | 🧱 **工程** | 100% TypeScript，严格模式 · 小依赖表面 · stderr 仅日志。 | --- ## 🛠️ 工作原理 ``` ┌──────────────────────────────────────────────┐ 您 ◀──────▶ │ AI 助手（Claude / Cursor / Continue …） │ └───────────────────────┬──────────────────────┘ stdio · JSON-RPC（MCP） ┌───────────────────────▼──────────────────────┐ │ Proxmox MCP 服务器 │ │ 配置 → 身份验证 → 工具调用 → Proxmox API │ └───────────────────────┬──────────────────────┘ HTTPS · /api2/json（令牌或票证） ┌───────────────────────▼──────────────────────┐> │ Proxmox VE 节点 / 集群 (:8006) │ └───────────────────────────────────────────────┘ ``` 服务器调用 **Proxmox VE REST API**（`https://<host>:8006/api2/json）。它自动从 `/cluster/resources` 解析每个虚拟机的节点，因此您只需按 **VMID 或名称** 地址虚拟机和容器 — 无需知道它们位于哪个节点。 --- ## ✅ 需求 | 需求 | 说明 | | --- | --- | | **Node.js ≥ 18** | ES 模块 + 全局 `fetch`。建议 Node 20+。 | | **Proxmox VE 7/8 节点或集群** | 在其 API 端口（`8006`）可访问。 | | **API 令牌**（推荐） | 或用户/密码。参见 [创建 Proxmox API 令牌](#-create-a-proxmox-api-token)。 | | **MCP 客户端** | Claude Desktop、Cursor、Continue、Zed 或 MCP 检查器。 | --- ## 📦 安装 ```bash git clone https://github.com/soyrageagency/proxmox-mcp-server.git cd proxmox-mcp-server npm install npm run build ### 🧪 尝试它 - 演示模式（不需要 Proxmox） 现在想立即评估它吗？运行 **演示模式** — 服务器提供一个令人信服的假数据（不需要实际主机）。 ```bash npm run build PROXMOX_MCP_DEMO=true npm run inspect # 在 MCP 检查器中探索每个工具 ``` 或指向克劳德桌面使用 `"PROXMOX_MCP_DEMO": "true"` 在 `env` 块并询问 *“列出我的 Proxmox 虚拟机和容器。”* 您将获得类似的输出： ``` VMID 类型 名称 节点 状态 CPU 内存 运行时间 100 VM web pve running 3.1% 1.8 GB/4.0 GB 22d 23h 101 VM db pve running 8.7% 6.2 GB/8.0 GB 22d 23h 200 CT nginx-proxy pve running 0.4% 96.0 MB/512 MB 22d 22h 201 CT grafana pve running 1.2% 240 MB/2.0 GB 13d 21h ``` 当您准备就绪时，设置 `PROXMOX_MCP_DEMO=false` 并添加您的真实主机 + 令牌。 ### 使用真实集群 ```bash npm run inspect # 设置 PROXMOX_HOST + 令牌后（见下文） ``` --- ## ⌨️ 终端 UI（TUI） 更喜欢终端吗？启动 **`proxmox-mcp-tui`** — 一个创意、专业、类似 [lazydocker](https://github.com/jesseduffield/lazydocker) 风格的集群仪表盘，通过 SoyRage Agency 欢迎，然后进入实时、键盘驱动的视图。 ```bash npm run build npm run tui # → 交互式终端仪表盘 npm run tui:demo # 相同，带有逼真的模拟数据（无需集群） ``` <div align="center"> ### 欢迎 <img src="./assets/screenshots/tui-welcome.png" alt="SoyRage Agency Proxmox 终端欢迎" width="80%"> ### 客机 — 操作系统、实时仪表盘和一键操作 <img src="./assets/screenshots/tui-dashboard.png" alt="Proxmox MCP 终端 UI 由 SoyRage Agency 提供" width="92%"> ### 标签页视图 — 节点 · 存储 · 任务 <img src="./assets/screenshots/tui-storage.png" alt="Proxmox MCP 终端 UI 存储视图 由 SoyRage Agency 提供" width="92%"> ### 🤖 用自然语言给 AI 下达命令 <img src="./assets/screenshots/tui-ai.png" alt="Proxmox MCP 终端 UI AI 命令栏 由 SoyRage Agency 提供" width="92%"> <sub>在 **演示模式** 下渲染 · 水印 © SoyRage Agency · soyrage.es</sub> </div> **功能** - **标签页视图** — `1` 客机 · `2` 节点 · `3` 存储 · `4` 任务（或 `Tab` 循环），每个都有列标题和利用率条。 - **🤖 AI 命令栏** — 按 `a` 并在自然语言中输入命令：*“重启 db”*、*“关闭 200”*、*“哪些虚拟机已关闭？”*、*“web 使用了多少 RAM？”*。AI 建议操作并询问您 **确认** 然后执行 — 问题会立即得到答案。由任何 OpenAI 兼容的端点提供支持（OpenAI、**Ollama**、LM Studio…）；演示模式模拟它。 - **实时** — 标题中的时钟和集群名称，每 5 秒自动刷新。 - **搜索** — 按 `/` 筛选虚拟机名称或 VMID。 - **帮助叠加层** — 按 `?` 获取键盘快捷键表。 - **安全操作** — 破坏性 `stop` 和每个 AI 操作都需要 `y/n` 确认；只读模式隐藏所有操作键。 - **丰富细节** — 所选虚拟机显示其 **操作系统**（通过 QEMU 代理）、CPU/内存/磁盘仪表盘、核心和运行时间；按 `s` 查看其快照。 **按键：** `1-4`/`Tab` 视图 · `↑/↓`（或 `j/k`）导航 · `/` 筛选 · **`a` 问 AI** · `s` 快照 · `S` 启动 · `d` 关闭 · `x` 停止 · `b` 重启 · `r` 刷新 · `?` 帮助 · `q` 退出。虚拟机为青色，容器为洋红色。 > 💡 使用 `PROXMOX_MCP_AI_ENDPOINT`（+ `_KEY`， `_MODEL`）启用 AI。适用于 **Ollama** 本地免费。无 AI 时，栏仍通过内置规则引擎理解常见命令。 --- ## 🔑 创建 Proxmox API 令牌 API 令牌是身份验证最安全的方式（无需存储密码，可撤销，可范围限定）。 1. 在 Proxmox 网页界面前往 **数据中心 → 权限 → API 令牌 → 添加**。 2. 选择一个 **用户**（例如 `root@pam`）和一个 **令牌 ID**（例如 `mcp`）。复制生成的 **密钥** — 它只显示一次。 - 您的 `PROXMOX_TOKEN_ID` 然后是 **`root@pam!mcp`**。 3. 授予令牌权限。对于完全控制，分配 `/` 路径下的 `PVEAdmin` 角色；对于 **只读**，使用 `PVEAuditor`。（取消勾选 *权限分离* 以继承用户的权限，或为令牌添加 ACL。） 4. 将值放入您的 MCP 客户端配置 / `.env`： ``` PROXMOX_HOST=https://192.168.1.10:8006 PROXMOX_TOKEN_ID=root@pam!mcp PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` > 优先使用最小权限：配对 `PVEAuditor` 令牌和 `PROXMOX_MCP_READONLY=true` 以获得安全、仅查看的助手。 --- ## 🔌 连接到你的 AI 客户端 将服务器添加到您的 MCP 客户端。示例适用于 **Claude Desktop** （`%APPDATA%\Claude\claude_desktop_config.json` 在 Windows 上， `~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上）： ```jsonc { "mcpServers": { "proxmox": { "command": "node", "args": ["/absolute/path/to/proxmox-mcp-server/dist/index.js"], "env": { "PROXMOX_HOST": "https://192.168.1.10:8006", "PROXMOX_TOKEN_ID": "root@pam!mcp", "PROXMOX_TOKEN_SECRET": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "PROXMOX_VERIFY_TLS": "false", "PROXMOX_MCP_READONLY": "false" } } } } ``` 一个可编辑的副本位于 [`examples/claude_desktop_config.json`](./examples/claude_desktop_config.json)。重启您的客户端并询问：*“我的 Proxmox 节点和虚拟机是什么？”* — 助手将以 SoyRage Agency 的名义向您问候，并接管。 --- ## ⚙️ 配置参考 每个设置都是一个环境变量。自动加载本地 **`.env`**；JSON **配置文件** (`proxmox-mcp.config.json`) 提供默认值。优先级（低 → 高）：默认值 → 配置文件 → `.env` → 环境。参见 [`.env.example`](./.env.example)。 | 变量 | 默认值 | 说明 | | --- | --- | --- | | `PROXMOX_HOST` | — | API 基本 URL，例如 `https://192.168.1.10:8006`。 | | `PROXMOX_TOKEN_ID` | — | API 令牌 ID `user@realm!tokenname`（推荐）。 | | `PROXMOX_TOKEN_SECRET` | — | API 令牌密钥（UUID）。 | | `PROXMOX_USER` | — | `user@realm` 用于票证身份验证（如果未提供令牌）。 | | `PROXMOX_PASSWORD` | — | 票证身份验证的密码。 | | `PROXMOX_VERIFY_TLS` | `false` | 验证节点的 TLS 证书。 | | `PROXMOX_MCP_READONLY` | `false` | 隐藏 **所有** 状态更改工具。 | | `PROXMOX_MCP_DEMO` | `false` | 提供编造的演示数据（无需真实主机）。 | | `PROXMOX_MCP_ALLOWLIST` | — | AI 可以触摸的 VMID/名称的逗号分隔列表（空 = 所有）。 | | `PROXMOX_MCP_PLUGINS` | — | 仅加载这些插件（空 = 所有）。 | | `PROXMOX_MCP_DISABLED_PLUGINS` | — | 禁用这些插件。`about` 已锁定。 | | `PROXMOX_MCP_LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error`。 | | `PROXMOX_MCP_AI_ENDPOINT` | — | TUI 的 AI 副驾驶的 OpenAI 兼容基本 URL（空 = 基于规则）。 | | `PROXMOX_MCP_AI_KEY` | — | AI 端点的 Bearer 密钥。 | | `PROXMOX_MCP_AI_MODEL` | `gpt-4o-mini` | AI 端点的模型名称。 | | `PROXMOX_MCP_CONFIG` | `proxmox-mcp.config.json` | 可选的 JSON 配置文件路径。 | --- ## 🔒 TLS 自签名证书 Proxmox 默认提供一个 **自签名证书**，因此对于大多数家庭实验室，`PROXMOX_VERIFY_TLS=false`（默认值）是预期的 - 连接仍然是加密的，只是没有证书验证。TLS 控制是按请求（通过 `undici`）进行的，因此它 **不会**全局禁用您进程的验证。 仅当您的节点呈现一个受您的系统信任的证书（例如 Let's Encrypt 证书，或位于 `:8006` 前面的内部 CA / 反向代理）时，才设置 `PROXMOX_VERIFY_TLS=true`。 ## 🛡️ 安全模型与网络 此服务器可以控制您的基础设施 - 请像对待 `root` SSH 一样谨慎操作。 | 控制 | 功能 | | --- | --- | | **只读模式** (`PROXMOX_MCP_READONLY=true`) | 隐藏所有生命周期/快照变更工具。与 `PVEAuditor` 令牌配对使用。 | | **允许列表** (`PROXMOX_MCP_ALLOWLIST`) | 限制所有 guest 工具仅限于匹配的 VMID/名称；其他情况返回明确错误。 | | **范围限定 API 令牌** | 仅授予令牌所需的权限；在 UI 中立即撤销。 | | **最小特权** | `PVEAuditor` + 只读 = 一个安全、仅限查看的助手。 | **网络：** Proxmox API 监听 `:8006`。通过 **VPN**（[WireGuard](https://www.wireguard.com/) / [Tailscale](https://tailscale.com/)）而不是将 `8006` 暴露给 Internet 来访问远程节点。MCP 服务器在您的 AI 客户端旁边本地运行，并连接到 Proxmox - 它自己不打开任何入站端口。 ### 安全配方 ```bash # 只读助手（非常适合演示/仪表盘） PROXMOX_MCP_READONLY=true # + 一个 PVEAuditor 令牌 # 只允许 AI 管理两个特定的 guest PROXMOX_MCP_ALLOWLIST=101,web # 仅暴露集群/ guest 洞察力，没有存储/任务 PROXMOX_MCP_PLUGINS=nodes,guests,cluster ``` ## 🧰 完整工具参考 标记为 **W** 的工具会更改状态，当 `PROXMOX_MCP_READONLY=true` 时会被 **隐藏**。 guest 可以通过 **VMID 或名称**来寻址。 ### 身份 | 工具 | 描述 | | --- | --- | | `about` | 致谢，许可证和 SoyRage Agency 欢迎横幅。 | | `list_plugins` | 模块化插件及其是否启用。 | ### 洞察（只读） | 工具 | 参数 | 描述 | | --- | --- | --- | | `list_nodes` | — | 集群节点，状态，CPU 和内存。 | | `node_status` | `node` | 一个节点的详细状态。 | | `list_guests` | `kind?` (`qemu`/`lxc`)，`runningOnly?` | 所有具有实时统计数据的 VM 和容器。 | | `guest_status` | `guest` | 一个 VM/容器的实时状态。 | | `guest_config` | `guest` | 一个 guest 的完整配置。 | | `guest_osinfo` | `guest` | guest 的 **操作系统**（代理名称/版本 + IP 地址）。 | | `list_storage` | `node` | 节点上的存储及其使用情况。 | | `list_tasks` | `node`，`limit?` | 节点上的近期任务。 | | `cluster_status` | — | 集群成员资格和法定人数。 | | `cluster_resources` | `type?` | 整合的节点/guest/存储视图。 | | `list_snapshots` | `guest` | VM/容器的快照。 | | `list_backups` | `node?`，`storage?` | 具有 VMID，大小，年龄的 vzdump 备份存档。 | | `list_templates` | `node?` | 容器模板（vztmpl）和安装 ISO。 | ### 生命周期（**W**） | 工具 | 参数 | 描述 | | --- | --- | --- | | `start_guest` | `guest` | 启动 VM/容器。 | | `shutdown_guest` | `guest`，`timeout?` | 正常 ACPI/OS 关闭（首选）。 | | `stop_guest` | `guest` | 硬停止（电源线）。破坏性 - 请先确认。 | | `reboot_guest` | `guest` | 正常重启。 | | `suspend_guest` | `guest`，`toDisk?` | 在 RAM 中暂停 VM（或休眠到磁盘）。 | | `resume_guest` | `guest` | 恢复暂停的 VM。 | ### 管理（**W**） | 工具 | 参数 | 描述 | | --- | --- | --- | | `migrate_guest` | `guest`，`target`，`online?` | 将 guest 移动到另一个节点（如果正在运行，则为实时迁移）。 | | `clone_guest` | `guest`，`newid`，`name?`，`full?`，`target?` | 从模板克隆 VM/CT。 | | `set_guest_resources` | `guest`，`cores?`，`memory?` | 快速更改 CPU 核心/RAM（MB）。 | | `backup_guest` | `guest`，`storage`，`mode?`，`compress?` | 创建存储到 vzdump 备份。 | | `delete_guest` | `guest`，`confirm`，`purge?` | 销毁 guest（保护：`confirm` 必须等于 VMID）。 | ### 备份和配置（**W**） | 工具 | 参数 | 描述 | | --- | --- | --- | | `restore_backup` | `volid`，`vmid`，`node?`，`storage?`，`force?` | 将 vzdump 存档恢复到 VMID。 | | `create_container` | `vmid`，`ostemplate`，`storage`，`hostname?`，`cores?`，`memory?`，`diskGb?`，… | 从模板创建 LXC 容器。 | | `create_vm` | `vmid`，`storage`，`name?`，`diskGb?`，`cores?`，`memory?`，`iso?`，`ostype?`，… | 创建 QEMU VM（具有磁盘 + 可选安装 ISO）。 | ### 快照（**W**） | 工具 | 参数 | 描述 | | --- | --- | --- | | `create_snapshot` | `guest`，`name`，`description?`，`withRam?` | 获取快照（可选地包含 VM RAM）。 | | `rollback_snapshot` | `guest`，`name` | 回滚到快照（破坏性）。 | | `delete_snapshot` | `guest`，`name` | 删除快照。 | ## 💬 示例对话 | 您说… | 助手调用… | | --- | --- | | “显示我所有的 VM 和容器。” | `list_guests` | | “哪些容器正在运行？” | `list_guests { kind: "lxc", runningOnly: true }` | | “节点 pve 是否健康？” | `node_status { node: "pve" }` | | “VMID 101 怎么样了？” | `guest_status { guest: "101" }` | | “在升级前对 db 进行快照。” | `create_snapshot { guest: "db", name: "pre-upgrade" }` | | “正常关闭容器 200。” | `shutdown_guest { guest: "200" }` | | “pve 上的存储空间有多满？” | `list_storage { node: "pve" }` | | “最近 pve 上发生了什么？” | `list_tasks { node: "pve" }` | | “谁创建了这个？” | `about` | ## 🧩 模块化插件架构 服务器由独立的 **插件** 组装，每个插件拥有一个功能组；加载由配置完全驱动。`about` 插件是 **锁定** 的 - 它带有 SoyRage Agency 身份识别，无法禁用。 | 插件 | 类别 | 类型 | 工具 | | --- | --- | --- | --- | | `about` 🔒 | 身份识别 | 读取 | `about`，`list_plugins` | | `nodes` | 节点 | 读取 | `list_nodes`，`node_status` | | `guests` | guest | 读取 | `list_guests`，`guest_status`，`guest_config`，`guest_osinfo` | | `storage` | 存储 | 读取 | `list_storage` | | `tasks` | 任务 | 读取 | `list_tasks` | | `cluster` | 集群 | 读取 | `cluster_status`，`cluster_resources` | | `snapshots` | 快照 | 读取/写入 | `list_snapshots`，`create/rollback/delete_snapshot` | | `lifecycle` | 生命周期 | 写入 | `start/shutdown/stop/reboot/suspend/resume_guest` | | `management` | 管理 | 写入 | `migrate/clone/backup/delete_guest`，`set_guest_resources` | | `backups` | 备份 | 读取/写入 | `list_backups`，`restore_backup` | | `provisioning` | 配置 | 读取/写入 | `list_templates`，`create_container`，`create_vm` | ```bash PROXMOX_MCP_PLUGINS= # （环境变量）为空 = 加载所有 PROXMOX_MCP_DISABLED_PLUGINS=lifecycle,snapshots # 仅限洞察 ``` 随时向助手 **“列出插件”** 以查看已启用的插件。 ## 🗂️ 项目结构 ``` proxmox-mcp-server/ ├── assets/soyrage-banner.svg # SoyRage Agency 标识横幅 ├── examples/ # Claude 配置 + 配置文件示例 ├── install.sh / install.ps1 # 面向初学者的一键引导 ├── scripts/install.mjs # 跨平台 Claude Desktop 配置工具 ├── src/ │ ├── index.ts # 入口点：横幅，归属保护，线路 │ ├── branding.ts # SoyRage 标识，ASCII 横幅，MCP 说明 │ ├── plugins.ts # 模块化插件目录和加载器 │ ├── config.ts # 分层配置（默认值 → 文件 → .env → 环境变量） │ ├── logger.ts # 仅标准错误的结构化日志记录 │ ├── proxmox/ │ │ └── client.ts # 类型化的 Proxmox VE API 客户端（令牌/票据，TLS） │ ├── tools/ # 每个插件的工具模块 │ │ ├── context.ts · about.ts · nodes.ts · guests.ts · cluster.ts │ │ ├── storage.ts · tasks.ts · snapshots.ts · lifecycle.ts │ └── utils/ # format.ts（表格/单位）· result.ts（MCP 帮助程序） ├── .env.example · LICENSE · NOTICE · README.md ``` ## 🧪 开发 ```bash npm run dev # 使用 tsx 热重载 npm run typecheck # 严格类型检查，无输出 npm run build # 编译到 dist/ npm run start # 运行已编译的服务器 npm run inspect # 启动 MCP 检验工具 npm run setup # 构建 + 配置 Claude Desktop ``` **设计说明：** 标准输出保留用于 JSON-RPC 流（日志 → 标准错误）；Proxmox 客户端自动解析 guest → 节点；失败的工具调用返回一个干净的 `isError` 结果，而不是使连接崩溃；TLS 控制通过 `undici` 按请求进行。 ## 🩺 故障排除和常见问题 <details><summary><b>“无法访问 Proxmox API。”</b></summary> 检查 `PROXMOX_HOST`（包括 `https://` 和 `:8006`），确保节点可访问（VPN？），以及您的令牌/凭证。使用自签名证书时，请保留 `PROXMOX_VERIFY_TLS=false`。服务器继续运行，因此工具调用在您的聊天客户端中返回友好的错误。 </details> <details><summary><b>401 / 权限被拒绝。</b></summary> 令牌/用户缺乏该路径的权限。为路径 `/` 或特定 VM 分配适当的角色（`PVEAuditor` 用于读取，`PVEAdmin`/`PVEVMAdmin` 用于控制），并确保令牌不受 *权限分离* 的限制，且没有 ACL。 </details> <details><summary><b>助手无法看到启动/停止工具。</b></summary> 您处于只读模式（`PROXMOX_MCP_READONLY=true`）或 `lifecycle` 插件已禁用。调整并重启您的 MCP 客户端。 </details> <details><summary><b>我的数据是否被发送到其他地方？</b></summary> 否。服务器仅与您的 Proxmox API 和您的 MCP 客户端通过本地标准输入/输出通信。它不进行其他任何出站调用。 </details> ## 🗺️ 路线图 - [x] 节点，guest，生命周期，快照，存储，任务，集群 - [x] guest **操作系统** 检测（QEMU 代理）· 挂起/恢复 - [x] **迁移**，**克隆**，**调整大小**，**备份**（vzdump），**删除** guest - [x] **备份**：列出和 **恢复** 存档 · **配置**：从模板和 ISO 创建 VM/CT - [x] 引导设置向导 · API 令牌和票证身份验证 · 只读和允许列表 · 模块化插件 - [x] 一键安装程序 · 演示模式 · 终端 UI（TUI）· CI - [ ] 调度备份作业和备份修剪 - [ ] Cloud-init 配置预设 - [ ] 发布 npm 包，用于单行 `npx` 使用 ## 💙 支持项目 Proxmox MCP 服务器由 **SoyRage Agency** 在开放状态下构建和维护。如果它有用，请考虑支持持续开发 - 它资助新功能并使项目保持免费。 <div align="center"> [](https://www.paypal.com/paypalme/soyrageagency) **paypal.me/soyrageagency** · 在存储库上加 ⭐ 也很有帮助！ </div> 其他帮助方式： 在 r/selfhosted 或 r/Proxmox 上分享，报告问题，开启 PR，或聘请 [SoyRage Agency](https://soyrage.es/) 进行自定义 DevOps + AI 工具开发。 ## 🖋️ 致谢与许可证 <div align="center"> **由 [SoyRage Agency](https://soyrage.es/) 设计、构建和维护 - https://soyrage.es/** </div> 在 **SoyRage Attribution License** 下发布（参见 [`LICENSE`](./LICENSE) 和 [`NOTICE`](./NOTICE)）。您可以自由使用、修改和自我托管 - **只要 SoyRage Agency 的署名保持可见**：源代码头、`package.json` 作者字段和运行时身份识别（ASCII 横幅、`about` 工具、MCP `instructions`）必须保持完整。 > ℹ️ **关于署名：** 在您的机器上运行的软件始终可以被修改 - 这不是 DRM。署名在所有地方都是默认的，因此删除它是一种刻意的行为，而许可证使这种行为成为违反行为。对于白标或商业许可证，请通过 **[soyrage.es](https://soyrage.es/)** 联系我们。 <div align="center"> **© 2026 SoyRage Agency - https://soyrage.es/** · 在西班牙瓦伦西亚精心制作。 </div>