RekklesNA/ProxmoxMCP-Plus

Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.

总体概览： ProxmoxMCP-Plus 是一个控制层，允许 AI 助手（以及普通 HTTP 工具）操作 Proxmox VE 虚拟化服务器——通过统一且注重安全的接口创建虚拟机、管理 Linux 容器 (LXC)、拍摄快照、运行备份、拉取 ISO。操作员无需手动编写原始 Proxmox API 调用和 shell 脚本，只需设置一次此服务器并将工具指向它即可。

它解决的问题

Proxmox VE 是托管虚拟机和容器的底层系统。通常，要对其执行自动化任务，您需要拼凑原始 API 调用、临时脚本和自定义作业轮询循环。该项目用一个支持两种行业标准语言的单一工具取代了这种拼凑方案：

MCP (Model Context Protocol)：Claude Desktop、Cursor、VS Code 或 Open WebUI 等 AI 代理与外部工具通信的方式。这是“AI 客户端”路径。
OpenAPI (REST/HTTP)：传统仪表板、内部脚本和无代码自动化平台调用服务的方式。这是“标准 HTTP”路径。

两条路径都进入相同的工作流，因此您可以选择使用其中之一（或两者），而无需学习两种不同的系统。

它的实际功能

根据 README，操作范围包括：

VM 和 LXC 生命周期操作 — 启动、停止、创建、删除虚拟机和容器
快照 — 创建、回滚、删除
备份和恢复工作流
ISO 下载和清理 — 获取安装镜像并删除旧镜像
节点、存储和集群检查 — 检查虚拟机管理程序及其环境的健康状况和状态
基于 SSH 的容器命令 — 在带有护栏的容器内运行命令（可选；需要 SSH 配置）
可选的受保护节点 SSH 命令 — 在 Proxmox 主机本身上运行命令，同样受到保护且可选
持久化作业跟踪 — 长时间运行的 Proxmox 任务获得稳定的作业 ID (job_id)，跟踪 Proxmox UPID，并支持轮询、重试、取消和审计历史记录

如何运行

README 提供了三种主要的运行路径：

来自 PyPI 的 MCP stdio — 本地 AI 客户端（Claude Desktop、Cursor、VS Code）的经典方式。使用 uvx proxmox-mcp-plus 或 pip install proxmox-mcp-plus 启动。
通过 Docker 的原生 MCP HTTP — 适用于支持“Streamable HTTP”传输的远程 MCP 客户端。在端口 8000 的 /mcp 上启动，需要通过 MCP_API_KEY 提供 API 密钥。
通过 Docker 的 OpenAPI 网桥 — 默认的 Docker 模式，在端口 8811 上提供 REST 端点，由 PROXMOX_API_KEY 保护。健康检查端点位于 /livez，规范位于 /openapi.json。

在执行上述任何操作之前，您需要创建一个 Proxmox API 令牌，将 proxmox-config/config.example.json 复制到 proxmox-config/config.json，并填写主机、端口、用户和令牌详细信息。（可选添加 ssh 和 jobs 部分。）

安全特性

README 强调了“注重安全”的设计：

Proxmox API 令牌，具有最小权限
Bearer 令牌认证，用于 OpenAPI 网桥
命令策略 — 管理允许哪些容器/主机命令的规则
审批令牌 — 运维人员可以要求对某些操作进行明确的人工审批
TLS 验证 — 默认验证 SSL 证书
MCP HTTP 主机/来源控制 — DNS 重绑定保护和允许列表来源
工具暴露过滤 — 可选的允许列表/拒绝列表，用于限制服务器发送给客户端的工具模式；空列表禁用所有内容，未知名称会导致启动失败，且仅精确的小写名称有效

代码模式 (可选)

默认情况下，服务器公开完整的工具目录。如果您设置 mcp.code_mode: true（或 MCP_CODE_MODE=true），它将切换为仅三个工具：

proxmox_code_search — 发现可用内容
proxmox_code_get_schema — 获取参数模式
proxmox_code_execute — 针对域工具运行脚本表达式

代码执行在隔离的沙盒中运行（除了注册的工具调用外，没有文件系统或网络访问权限），并具有严格限制：64,000 个源字符、100 MB 内存、25 次工具调用、16 KB 最终 JSON、两次并发执行以及 30 秒预算。取消或失败脚本不会回滚工具的副作用——因此您不应自动重试失败的变更。提供可选的工作池重用 (mcp.code_mode_pool_reuse)。

OAuth 浏览器门控 (可选，原生 MCP HTTP)

一种针对远程 MCP 客户端的更复杂的认证流程：用户无需发送原始 API 密钥，而是通过带有 PKCE（一种安全登录标准）的 OAuth 授权码流程，人类唯一需要的凭据是 MCP_API_KEY。浏览器访问同意页面，审查客户端请求的内容，并输入密钥。OAuth 状态存储在 PostgreSQL（而非本地文件）中，因此多个服务器实例可以安全地共享状态。服务器依赖 MCP Python SDK 进行协议端点处理，并添加了同意页面和 API 密钥策略。

切换 MCP_OAUTH_ENABLED=true 时的关键要求：MCP_OAUTH_ISSUER（公共 HTTPS 来源）、MCP_OAUTH_DATABASE_URL（PostgreSQL DSN）和 MCP_API_KEY。启用 OAuth 后，原始 Authorization: Bearer <key> 请求将被拒绝——仅已颁发的 OAuth 令牌有效。

差异点 (基于项目自身的表格)

优先级	方法
双重访问路径	在相同工作流上实现原生 MCP + OpenAPI
面向 Proxmox	基础之外的第 2 天操作：快照、备份、ISO、存储、集群
长时间运行的工作	稳定的作业 ID、UPID 跟踪、轮询、重试、取消、审计跟踪
更安全的执行	令牌、命令策略、审批、TLS 验证、主机/来源控制
真实验证	单元、集成、Docker/OpenAPI 以及实时 Proxmox 测试（在仓库中有记录）

总结

如果您运营 Proxmox VE 集群并希望 AI 代理或 HTTP 自动化安全地管理它，该项目为您提供了一个可安装的桥梁，具有两个接口、强大的安全态势以及针对 Proxmox 众所周知的异步任务的稳健作业跟踪。它可通过 JSON 文件和环境变量进行配置，从 PyPI 或 Docker 运行，并包含温和的护栏（允许列表、审批、沙盒），以便在您让自主代理接触您的基础设施时使用。