ProxmoxMCP-Plus

ProxmoxMCP-Plus

通过一个注重安全性的控制平面，使用 MCP 客户端、AI Agent 和 OpenAPI 工具管理 Proxmox VE，涵盖 VM、LXC、快照、备份、ISO、容器命令和持久化长时间运行的任务。

快速开始 | 客户端安装 | 演示 | 工具 | 安全性 | 场景 | 文档 | Wiki

MCP 和 OpenAPI 是进入相同工作流的替代入口，并且可以在独立进程中运行。实线箭头表示请求和执行；虚线箭头表示持久化的任务与审计状态。审批关卡、SSH 执行和 MCP HTTP OAuth 取决于配置。选择图表可查看大图。

为什么选择 ProxmoxMCP-Plus

ProxmoxMCP-Plus 位于 AI 客户端和 Proxmox VE 之间，让运维人员无需为每个工作流拼接原始 API 调用、一次性 Shell 脚本和自定义任务轮询。

它通过两种方式提供相同的运维功能：

• MCP，适用于 Claude Desktop、Cursor、VS Code、Open WebUI、Codex 及其他支持 MCP 的 Agent
• OpenAPI，适用于 HTTP 自动化、仪表板、内部工具和无代码工作流

你将获得：

• VM 和 LXC 生命周期操作
• 创建、回滚和删除快照
• 备份与恢复工作流
• ISO 下载与清理
• 节点、存储和集群检查
• 带防护措施的、基于 SSH 的容器命令执行
• 可选启用并受保护的 Proxmox 节点 SSH 命令
• 用于异步 Proxmox 任务的持久化任务跟踪

与众不同之处

优先事项	项目处理方式
双重访问路径	为 Agent 工作流提供原生 MCP，并通过 OpenAPI 实现标准 HTTP 自动化
面向 Proxmox 的工作流	第 2 天 VM、LXC、快照、备份、ISO、存储和集群操作
长时间运行的操作	稳定的 job_id、Proxmox UPID 跟踪、轮询、重试、取消和审计历史记录
更安全的执行	Proxmox API 令牌、OpenAPI bearer 身份验证、命令策略、审批令牌、TLS 验证以及 MCP HTTP Host/Origin 控制
实际验证	仓库中记录了单元、集成、Docker/OpenAPI 和实时 Proxmox 端到端验证入口

快速开始

1. 准备 Proxmox 凭据

创建一个 Proxmox API 令牌，并仅授予工作流所需的权限。然后创建本地配置文件：

cp proxmox-config/config.example.json proxmox-config/config.json

接着编辑 proxmox-config/config.json，填写环境信息。至少需要配置：

• proxmox.host
• proxmox.port
• auth.user
• auth.token_name
• auth.token_value

如果需要执行容器命令，也请添加 ssh 部分。 如果希望将作业状态持久化到默认本地 SQLite 文件以外的位置，请添加 jobs 部分。

如需进行真实环境验证，请使用 proxmox-config/config.live.example.json 创建单独的 proxmox-config/config.live.json。 除非你有意在本地 API 隧道上运行本地端到端测试，否则不要将实时端到端测试指向占位配置或仅供本地使用的 config.json。

可选的作业持久化配置：

{
  "jobs": {
    "sqlite_path": "proxmox-jobs.sqlite3"
  }
}

可选的工具暴露过滤功能可以减少发送给 MCP 客户端的架构数量。 默认情况下，此功能处于禁用状态，因此现有配置仍会暴露所有可用工具。在 mcp 下准确配置一种模式：

{
  "mcp": {
    "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  }
}

也可以使用 tool_denylist，或以逗号分隔的环境变量 MCP_TOOL_ALLOWLIST 和 MCP_TOOL_DENYLIST。不要同时配置两种模式。环境变量设置 会替换文件级过滤模式。允许列表为空时，不会暴露任何工具；拒绝列表为空时，不会隐藏任何工具。必须使用小写的工具名称；未知名称会导致启动失败，避免拼写错误意外扩大访问范围。更改过滤器后，请重启或重新连接 MCP 服务。

2. 选择一种运行方式

方式	最适合	启动命令	验证
通过 PyPI 使用 MCP stdio	Claude Desktop、Cursor、VS Code、Codex、本地 Agent	uvx proxmox-mcp-plus	客户端会列出 get_nodes、get_vms 和作业工具
通过 Docker 使用原生 MCP HTTP	支持 Streamable HTTP 的远程 MCP 客户端	docker compose --profile mcp-http up -d proxmox-mcp-http	连接到 http://localhost:8000/mcp
通过 Docker 使用 OpenAPI 桥接	HTTP 客户端、仪表板、脚本、无代码工具	docker compose --profile openapi up -d proxmox-mcp-api	curl -f http://localhost:8811/livez

Docker 示例默认会将主机端口发布到 127.0.0.1；Compose 模式需选择启用。只设置所选模式的密钥：原生 HTTP 使用 MCP_API_KEY，OpenAPI 使用 PROXMOX_API_KEY。有关反向代理、隧道、显式 LAN 绑定和容器重建，请参阅Compose 部署和升级说明。

使用 PyPI 运行 MCP stdio

uvx proxmox-mcp-plus

或者先安装：

pip install proxmox-mcp-plus
proxmox-mcp-plus

当 MCP 客户端会启动本地 stdio 服务时，请使用此方式。

Code Mode（可选启用）

默认情况下，Code Mode 处于禁用状态，以保留旧版完整工具目录。可在配置文件中设置 mcp.code_mode: true，或设置 MCP_CODE_MODE=true 来启用。启用后，MCP 会改为公开三个工具：proxmox_code_search、proxmox_code_get_schema 和 proxmox_code_execute。代码执行在隔离沙箱中运行，并通过现有的验证、策略和审批流程调用领域工具。发现功能使用经过筛选的运行时目录，因此在已安装的 wheel 中也能正常工作。例如：

await call_tool("get_nodes", {"target": "default"})

最终表达式会作为 data.result 返回；工具结果使用 MCP JSON 内容块（并在提供时包含结构化内容）。使用 proxmox_code_get_schema 获取参数，包括 target 和审批令牌。除已注册的工具调用外，脚本无法访问文件系统或网络。限制：源代码最多 64,000 个字符、沙箱内存 100 MB、25 次工具调用、最终 JSON 16 KB，以及最多同时执行两个任务。执行时限为 30 秒；取消或执行失败的脚本不会回滚工具副作用。不要自动重试执行失败的变更脚本。

可选的工作进程复用：设置 mcp.code_mode_pool_reuse: true 或 MCP_CODE_MODE_POOL_REUSE=true。默认情况下，每次执行都会启动一个全新的工作进程。启用复用后，服务的生命周期内最多保留两个工作进程，每个工作进程在被检出 100 次后回收，并为每个请求启动新的沙箱会话。不同请求之间不会共享全局变量、审批状态、输出收集器和调用次数限制。HTTP 客户端共用由服务持有的连接池；断开客户端不会关闭连接池。运行 python scripts/benchmark_code_mode.py 可测量本地启动开销；这是微基准测试，并非 Proxmox 操作延迟的估算值。

使用 Docker 部署原生 MCP HTTP

当远程 MCP 客户端支持 Streamable HTTP 时，可使用此方式：

export MCP_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

将 MCP 客户端指向：

http://127.0.0.1:8000/mcp

对于远程客户端，请使用已配置的代理／隧道 URL，或按照 Docker 部署中的说明显式扩大主机绑定范围。

每个原生 MCP HTTP 请求都必须附带 Authorization: Bearer <MCP_API_KEY>。此密钥独立于 Proxmox 凭据。默认情况下，原生 Streamable HTTP 和 SSE 都需要密钥。对于由 Tailscale ACL 等外部访问控制层保护的端点，可显式设置 MCP_ALLOW_UNAUTHENTICATED_HTTP=true，或在 JSON 配置中设置 mcp.allow_unauthenticated_http: true。这样可允许无密钥启动，并记录一条警告；但不会配置或验证外部访问控制。即使选择退出，只要配置了 MCP_API_KEY，仍始终会强制要求该密钥。此设置不会更改 OpenAPI 身份验证或 DNS 重绑定保护。

MCP 客户端的 OAuth 浏览器验证

原生 MCP HTTP 可选择性地提供带 PKCE 的 OAuth 授权码流程，同时仍仅要求操作员管理 MCP_API_KEY 这一人类凭据。OAuth 协议处理委托给 MCP Python SDK（mcp>=1.30.0,<2），而 ProxmoxMCP-Plus 提供 API 密钥授权策略和持久化 OAuth 状态。

OAuth 状态存储在 PostgreSQL 中。通过显式部署，多个 MCP 服务实例或主机可以共享已注册的客户端、授权码、访问令牌、刷新令牌、刷新令牌重放保护状态和登录速率限制状态，而无需依赖本地文件系统。

客户端从 SDK 的 /authorize 端点开始。SDK 验证客户端、重定向 URI、范围、PKCE 请求和资源后，浏览器会被重定向到同一 MCP 源站上的 /oauth/consent。用户查看客户端名称、重定向源站和请求的范围，然后输入 MCP_API_KEY。API 密钥绝不会出现在 URL 中，也绝不会返回给 OAuth 客户端。

必需的 OAuth 设置：

export MCP_API_KEY="$(openssl rand -hex 32)"
# Replace <password> with the database user's password.
export MCP_OAUTH_DATABASE_URL='postgresql://proxmox_oauth:<password>@postgres.example:5432/proxmox_oauth'

服务器示例：

docker run --rm -p 127.0.0.1:8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -e MCP_OAUTH_ENABLED=true \
  -e MCP_OAUTH_ISSUER=https://mcp.example.com \
  -e MCP_OAUTH_DATABASE_URL="$MCP_OAUTH_DATABASE_URL" \
  -e MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* \
  -e MCP_ALLOWED_ORIGINS=https://mcp.example.com \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

然后将支持 OAuth 的客户端连接到：

https://mcp.example.com/mcp

OAuth 模式会在同一公开源站上提供以下端点：

• /.well-known/oauth-protected-resource/mcp - RFC 9728 受保护资源元数据
• /.well-known/oauth-authorization-server - SDK 授权服务器元数据
• /register - SDK 动态客户端注册（DCR）
• /authorize - SDK 授权端点
• /token - SDK 授权码／刷新令牌交换
• /oauth/consent - ProxmoxMCP-Plus API 密钥授权页面

SDK 要求使用 PKCE S256，并通过签发的 OAuth 访问令牌保护 MCP 资源。浏览器授权事务具有较短的有效期，采用 HMAC 签名且无状态。所有持久化的 OAuth 状态都存储在 PostgreSQL 中。

授权码的使用和刷新令牌的轮换都通过 PostgreSQL 事务完成。系统会删除授权码或刷新令牌，并以原子方式插入替换令牌，因此并发运行的服务实例无法成功重放同一凭据。动态客户端注册容量也通过 PostgreSQL 事务级咨询锁进行串行化；在超过配置的上限前，会清理非活跃注册。

MCP_API_KEY 是浏览器授权凭据的唯一真实来源。此运行时不会在 PostgreSQL 中持久化该密钥或其验证器。服务进程会直接根据其环境中提供的值验证授权。如果服务明确部署为多个容器或实例，请为每个实例配置相同的密钥。更改密钥前，请停止所有实例，然后使用新值重启／重新创建所有实例，再重新路由流量。现有 OAuth 客户端和已签发的令牌独立于浏览器访问门密钥，并会在过期或被撤销前保持有效。

启用 OAuth 时必需：

变量	用途
MCP_API_KEY	仅在授权页面输入的人工凭据
MCP_OAUTH_ISSUER	此 MCP 授权服务器的公开 HTTPS 源
MCP_OAUTH_DATABASE_URL	用于 OAuth 状态的 PostgreSQL DSN

可选 OAuth 环境变量：

变量	默认值	用途
MCP_OAUTH_RESOURCE	<issuer>/mcp	公开 MCP 资源标识符；必须使用签发者源
MCP_OAUTH_SCOPES	mcp	以逗号分隔的必需范围
MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS	3600	访问令牌有效期
MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS	2592000	刷新令牌有效期（30 天）
MCP_OAUTH_MAX_REGISTERED_CLIENTS	4096	清理非活跃客户端前可持久化的 DCR 客户端上限
MCP_OAUTH_DB_POOL_MIN_SIZE	1	每个 MCP 进程的最小 asyncpg 连接数
MCP_OAUTH_DB_POOL_MAX_SIZE	10	每个 MCP 进程的最大 asyncpg 连接数
MCP_OAUTH_DB_COMMAND_TIMEOUT_SECONDS	10	OAuth 存储使用的 PostgreSQL 命令超时时间
MCP_OAUTH_CLIENT_IP_HEADER	未设置	仅用于登录速率限制的受信任反向代理标头

要轮换浏览器访问门凭据，请停止所有使用此签发者的 MCP 实例，在部署环境中更新 MCP_API_KEY，然后使用同一个新密钥重启／重新创建所有实例。提供程序启动时会读取环境；编辑正在运行的容器环境不会重新加载其密钥。无需更新 OAuth 数据库元数据或密钥版本。使用旧密钥创建的待处理授权事务，在所有实例重启后将无法再通过验证；已签发的 OAuth 令牌仍受其正常有效期和撤销规则约束。滚动更换密钥会导致旧实例继续接受旧密钥，而路由到不同密钥实例的授权请求会失败。没有数据库保护机制可检测或禁用过时实例。更改浏览器访问门密钥不会撤销现有访问令牌、刷新令牌或授权码；若 OAuth 凭据遭到泄露，请使用显式撤销。 从使用 MCP_OAUTH_KEY_VERSION 的 OAuth 构建版本升级时，启动过程会忽略旧变量，并保持 proxmox_mcp_oauth_metadata 不变。全新数据库不会创建该表。已注册的客户端和已签发的 OAuth 凭据会保留；无需手动执行 SQL 迁移。保留旧元数据可避免破坏旧工作进程的查询，并允许使用相同的 API 密钥和旧密钥版本回滚。升级前请备份数据库，并在轮换密钥前停止所有旧实例。密钥更改后，旧元数据仍描述旧密钥：回滚需要恢复旧配置，或遵循旧版本的轮换流程；此操作会使 OAuth 状态失效。只有在所有旧实例都已停用且不再需要回滚后，才手动删除旧表；其中仍可能包含前一个密钥的验证值。

数据库角色必须能够在其数据库中创建和修改 proxmox_mcp_oauth_* 表。这些表包含 OAuth 客户端元数据（包括已签发的客户端密钥）、授权码和有效令牌，因此必须将 PostgreSQL 数据库和备份作为凭据存储进行保护。

如果多个 MCP 实例使用相同的 MCP_OAUTH_DATABASE_URL，它们会共享 OAuth 状态和一次性令牌执行机制。规划数据库容量时，请考虑 MCP 进程的总数，因为配置的连接池限制适用于每个进程。

如果服务位于受信任的反向代理之后，且每用户登录速率限制必须使用原始客户端地址，请将 MCP_OAUTH_CLIENT_IP_HEADER 设置为代理会覆盖的标头（例如 CF-Connecting-IP）。除非代理能够阻止客户端伪造该标头，否则请勿设置此变量。

当 MCP_OAUTH_ENABLED=true 时，直接向 /mcp 发送 Authorization: Bearer <MCP_API_KEY> 请求会被有意拒绝。API 密钥仅在授权页面接受；MCP 请求必须使用已签发的 OAuth 访问令牌。

通过反向代理提供 MCP HTTP 服务时，请保持 DNS 重绑定保护启用，并且只允许预期的主机名。

使用 Docker 的 OpenAPI 桥接

OpenAPI 模式是 Docker 运行时的默认模式，并且需要 API 密钥：

export PROXMOX_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8811:8811 \
  -e PROXMOX_API_KEY="$PROXMOX_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

验证 OpenAPI 接口：

curl -f http://localhost:8811/livez
curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health
curl -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/openapi.json

仅用于本地无身份验证开发时，设置 PROXMOX_ALLOW_NO_AUTH=true。

检出源代码

git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus
uv venv
uv pip install -e ".[dev]"
python main.py

8811 服务是 OpenAPI/REST 桥接。8000 服务是原生 MCP HTTP 端点。

客户端安装

如果客户端支持 MCP 安装深层链接，请使用一键按钮；也可以复制下方的 JSON 配置。

推荐的 stdio 配置：

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-token",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_PORT": "8006",
        "PROXMOX_VERIFY_SSL": "true"
      }
    }
  }
}

如果不想在客户端配置中保存凭据，请使用本地配置文件：

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
      }
    }
  }
}

Claude Desktop、Cursor、VS Code、Codex、OpenCode、Open WebUI、Streamable HTTP 和 OpenAPI 的客户端示例，见客户端设置指南和集成指南。

演示

此演示是 qwen/qwen3.6-plus 在本地 Proxmox 实验环境中以英语驱动实时 MCP 会话的直接终端录屏。它展示了自然语言指令如何通过 MCP 工具创建并启动 LXC、执行容器命令，并确认经过身份验证的 HTTP /health 接口。

观看 MP4 版本

选择合适的工具

先进行只读发现，确认目标节点、存储、VMID 和权限后，再使用会修改状态的工具。

操作目标	从以下工具开始	然后使用	备注
检查集群	get_nodes、get_cluster_status	get_storage、get_vms、get_containers	安装客户端后，最适合先进行健康检查
创建或管理 VM	get_nodes、get_storage	create_vm、start_vm、stop_vm、delete_vm	长时间运行的修改操作会返回 job_id 和 Proxmox task_id
管理 LXC	get_containers、get_storage	create_container、start_container、stop_container、delete_container	基于 SSH 的命令工具需要可选的 ssh 配置
回滚有风险的更改	使用 vm_type=qemu 或 vm_type=lxc 的 list_snapshots	create_snapshot、rollback_snapshot、delete_snapshot	在进行破坏性工作流测试前创建快照
在客户机内运行命令	VM 或容器状态工具	execute_vm_command、execute_container_command	VM 路径需要 QEMU Guest Agent；LXC 路径需要通过 SSH 连接到 Proxmox 节点
跟踪异步任务	返回 job_id 的修改操作响应	poll_job、get_job、list_jobs、retry_job、cancel_job	在 Agent／用户对话中使用 job_id，使用 task_id 追踪原始 Proxmox 任务
检查日志	get_node_syslog、get_cluster_log	get_task_log、get_node_firewall_log、get_guest_firewall_log	所有日志工具均为只读；get_task_log 接受任何 Proxmox UPID
通过 HTTP 工具实现自动化	/openapi.json	/jobs、/health、生成的工具路由	使用 Bearer 身份验证，并在本地开发环境之外限制 CORS

如需查看完整的工具映射，请参阅 工具选择指南 和 API 与工具参考。

安全模型

ProxmoxMCP-Plus 是一个访问层，并不替代 Proxmox RBAC、网络控制或客户端上的 MCP 审批提示。

该项目为操作人员提供了多个控制点：

• Proxmox API 令牌决定后端可以执行哪些操作。
• 默认情况下，PROXMOX_API_KEY 会保护 OpenAPI 桥接服务。
• MCP_API_KEY 通过 Bearer 身份验证保护原生 Streamable HTTP 和 SSE；除非明确设置 MCP_ALLOW_UNAUTHENTICATED_HTTP=true 来委托访问控制，否则必须配置此项。
• 除非明确启用开发模式，否则会强制执行 TLS 验证。
• command_policy 控制命令执行和高风险操作。
• approval_token 可用于限制命令执行和高风险修改操作。
• MCP Streamable HTTP 部署可以启用 DNS 重绑定保护，并设置 Host 和 Origin 允许列表。
• 可选的 MCP 工具允许列表或拒绝列表可以缩小运行时工具范围，但不能替代 Proxmox RBAC。
• 日志经过设计，不会暴露命令和凭据内容。

在可信的本地环境之外公开服务之前，请阅读安全指南。

核心平台功能

ProxmoxMCP-Plus 提供统一的控制界面，涵盖大多数团队在 Proxmox VE 中实际需要的运维任务。同一服务既可将这些工作流提供给用于大模型和 AI Agent 场景的 MCP 客户端，也可通过 OpenAPI 桥接层提供给 HTTP 调用方。

支持的工作流领域：

功能领域	可用性
VM 创建 / 启动 / 停止 / 删除	可用
VM 快照创建 / 回滚 / 删除	可用
备份创建 / 恢复	可用
ISO 下载 / 删除	可用
LXC 创建 / 启动 / 停止 / 删除	可用
通过 SSH 在容器中执行命令	可用
更新容器的 authorized_keys	可用
用于长时间任务的持久化作业存储	可用
MCP 作业控制工具（list_jobs、get_job、poll_job、cancel_job、retry_job）	可用
带有明确状态码的 OpenAPI /jobs 端点	可用
本地 OpenAPI /livez、/readyz、/health 和架构	可用
Docker 原生 MCP Streamable HTTP（位于 /mcp）	可用
Docker 镜像构建和 /livez	可用

本仓库中的验证和契约入口：

• python -m pytest -q（完整 CI 覆盖率门槛请参阅贡献指南）
• ruff check .
• mypy src --ignore-missing-imports
• python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict
• tests/integration/test_real_contract.py
• tests/scripts/run_real_e2e.py

tests/scripts/run_real_e2e.py 现在优先使用 proxmox-config/config.live.json 或 PROXMOX_MCP_E2E_CONFIG。 这样可以避免意外使用特定机器的默认 config.json 运行实时检查。

长时间运行的作业

许多 Proxmox 变更操作都是异步的。ProxmoxMCP-Plus 现在通过持久化作业层封装这些任务，让 MCP 和 OpenAPI 客户端可以通过稳定的 Job ID 跟踪任务。

VM 创建 / 启动 / 停止、容器创建 / 启动 / 停止、快照变更、备份 / 恢复以及 ISO 下载 / 删除等长时间运行的工具现在会同时返回：

• task_id：原始 Proxmox UPID
• job_id：稳定的服务端作业记录

作业记录存储：

• 当前状态和进度
• 重试次数和先前的 UPID
• 最新结果载荷或失败原因
• 创建、轮询、重试和取消操作的审计历史

默认情况下，作业存储会持久化到 proxmox-jobs.sqlite3，因此重启不会丢失进行中或已完成作业的元数据。

审计事件会追加到单独的 SQLite 表中。现有历史记录会在启动时迁移，API 的 audit_log 格式保持不变。默认不限制保留时间；在 JSON 配置中将 jobs.audit_retention_days 设置为正数，即可在启动时以及每次作业更新时清理过期事件。这不会删除作业本身。进行此升级前，请停止所有共用该数据库的工作进程并备份数据库。不要让新旧版本同时使用同一个数据库；如果降级后需要保留审计历史，请恢复升级前的备份。

发出取消请求不代表任务已完成。调用 retry_job 前，请先轮询，直到任务失败 / 已取消；待处理的取消操作无法重试。

MCP 作业工具

• list_jobs
• get_job
• poll_job
• cancel_job
• retry_job

OpenAPI 作业路由

启用 OpenAPI 代理且有本地 JobStore 可用时，会直接公开以下路由：

路径	方法	用途	成功状态码
/jobs	GET	列出已持久化的作业	200
/jobs/{job_id}	GET	获取单个作业，可选 refresh=true	200
/jobs/{job_id}/poll	POST	从 Proxmox 刷新状态	200
/jobs/{job_id}/cancel	POST	请求取消	202
/jobs/{job_id}/retry	POST	重放已存储的重试方案	202

常见错误状态码：

• 404：未知的 job_id
• 409：作业存在，但当前无法执行该操作
• 503：启动 OpenAPI 代理时未提供本地 JobStore

tests/scripts/run_real_e2e.py 现在会优先使用 proxmox-config/config.live.json 或 PROXMOX_MCP_E2E_CONFIG。 这样可以避免意外使用特定于机器的默认 config.json 运行实时检查。

与常见方案的定位对比

能力	官方 Proxmox API	一次性脚本	ProxmoxMCP-Plus
面向 LLM 和 AI Agent 工作流的 MCP	否	否	是
面向标准 HTTP 工具的 OpenAPI 接口	否	通常没有	是
在一个接口中执行 VM 和 LXC 操作	仅底层操作	视情况而定	是
快照、备份和恢复工作流	仅底层操作	视情况而定	是
持久化异步作业跟踪和重试	否	少见	是
具备策略控制的容器命令执行	否	仅自定义实现	是
Docker 分发方式	否	少见	是
仓库级别的实时环境验证	不适用	少见	是

场景模板

可直接复制的示例位于 docs/examples/：

• 创建测试 VM
• 使用快照回滚有风险的更改
• 下载 ISO 并创建 LXC

这些示例面向人工操作人员和由 LLM 驱动的使用场景。

文档

README 特意针对在 GitHub 上快速了解项目进行了优化。更详细的运维文档位于 docs/wiki/，也可以发布到 GitHub Wiki。

如果你需要……	请从这里开始
了解项目和部署流程	Wiki 首页
配置并连接 Proxmox 环境	运维指南
连接 Claude Desktop、Cursor、VS Code、Codex、Open WebUI 或 HTTP 客户端	客户端设置指南
为工作流选择合适的工具	工具选择指南
查看文档质量目标、媒体计划和发布检查清单	文档质量计划
查看集成模式和传输详情	集成指南
从支持 MCP 的 IDE 和 Agent 安装	Agent 安装
通过 SSH 启用 LXC 命令执行	容器命令执行
查看安全性和命令策略	安全指南
查看工具参数、前置条件和行为	API 与工具参考
排查启动、身份验证或运行状况问题	故障排除
开发代码库或发布版本	开发者指南
查看发布和升级说明	发布与升级说明

已发布的 Wiki：

• GitHub Wiki 首页

仓库布局

• src/proxmox_mcp/：MCP 服务、配置加载、安全机制、OpenAPI 桥接
• main.py：用于本地和客户端驱动用法的 MCP 入口点
• docker-compose.yml：HTTP/OpenAPI 运行环境
• requirements/：辅助依赖来源和运行时安装列表
• scripts/：用于本地工作流的辅助启动脚本
• tests/scripts/run_real_e2e.py：实时 Proxmox 和 Docker/OpenAPI 路径
• tests/：单元测试和集成测试覆盖
• docs/examples/：基于场景的提示词和 HTTP 示例
• docs/wiki/：篇幅较长的运维、集成和参考文档

开发检查

请参阅贡献指南，了解环境设置、测试前提条件和拉取请求指南。

python -m pytest -q
ruff check .
mypy src --ignore-missing-imports
python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict
python -m build

CI 还会运行 PostgreSQL 支持的测试，并要求达到完整的运行时语句覆盖率，以及关键模块的完整分支覆盖率。有关确切的覆盖率命令，请参阅贡献指南；有关经过审查的运行时锁定工作流，请参阅依赖项更新。

社区

• 贡献指南
• 行为准则
• 无障碍
• 安全政策
• 报告问题
• 讨论

许可证

MIT

ISO 安装和 LXC 网络配置

使用 list_isos 查找现有 ISO 卷（或使用 download_iso 获取一个 ISO）。 create_vm 接受 iso_volume="local:iso/debian.iso"，默认将其挂载到 ide3，并优先从 CD-ROM 而非磁盘启动。update_vm_config 可挂载或更改该 ISO、使用 iso_volume="none" 弹出 ISO、设置 boot_order="scsi0;ide3"，或者更改 net0 上的 network_bridge，同时保留 MAC/VLAN/防火墙设置。请选择一个空闲的 cdrom_device；现有数据磁盘和 cloud-init 驱动器不会被替换。媒体和网桥编辑会读取当前配置，因此除了相关配置权限外，还需要 VM.Audit。仅更新现有的规格/cloud-init 配置仍然不需要预先读取。

LXC 使用操作系统模板，而非安装程序 ISO。create_container 默认保留 DHCP，现在还接受 network_bridge、ip="192.168.1.50/24"、gw="192.168.1.1"、ip6 和 gw6。update_container_network 会编辑现有接口上的这些字段（默认为 net0，也可选择 net31），并保留所有未指定的选项。使用空网关字符串可将其移除；更改为 DHCP/手动配置时，会移除对应地址族的旧网关。网络更改可能会中断来宾连接。两个编辑工具均遵循具名目标、只读和高风险审批策略。请将 update_container_network 添加到自定义高风险列表和所需工具许可名单中。升级详情请参阅 v0.5.19 发布说明。