ProxmoxMCP-Plus架构解析:MCP stdio、Streamable HTTP与OpenAPI桥三大入口如何协作?
ProxmoxMCP-Plus架构解析:MCP stdio、Streamable HTTP与OpenAPI桥三大入口如何协作?
ProxmoxMCP-Plus 是一个让 LLM 和 AI 智能体安全操作 Proxmox VE 的开源 MCP 服务器。它的核心设计是:一套工具核心,三个入口——MCP stdio 供 Claude Desktop、Cursor、VS Code 等客户端本地拉起;Streamable HTTP 供远程 MCP 客户端走网络访问;OpenAPI 桥则把同一套工具封装成标准 REST/Swagger 接口,供脚本、面板和无代码工作流调用。本文带你快速看懂这三条链路是如何共享同一个内核并协同工作的。
一个内核,三副面孔
三条入口共享同一个初始化流程。无论走哪条路,最终都会创建 src/proxmox_mcp/server.py 中的 ProxmoxMCPServer:
- 加载配置:读取
PROXMOX_MCP_CONFIG指向的 JSON(示例见 proxmox-config/config.example.json) - 建立目标连接:为每个 Proxmox target 创建
ProxmoxManager、命令策略门(CommandPolicyGate)和持久化JobStore - 注册工具:通过 src/proxmox_mcp/services/builtin_tool_plugins.py 统一注册 VM、LXC、快照、备份、日志、作业等全部内置工具
- 按 transport 分发:决定消息走标准输入输出,还是走 HTTP
关键在于 transport 选择逻辑,见 src/proxmox_mcp/server.py 的 start() 方法:
if transport == "STDIO":
anyio.run(self.mcp.run_stdio_async)
elif transport == "SSE":
anyio.run(self._run_sse_http_async)
elif transport == "STREAMABLE":
anyio.run(self._run_streamable_http_async)
transport 字段支持 STDIO、SSE、STREAMABLE 三个取值(定义在 src/proxmox_mcp/config/models.py),其中 STREAMABLE_HTTP 写法会自动归一化为 STREAMABLE(src/proxmox_mcp/config/models.py)。
入口一:MCP stdio——让 AI 客户端本地拉起服务器
这是默认模式,也是最简单的一条链路:MCP 客户端(Claude Desktop、Cursor、Codex 等)把服务器当成本地子进程启动,通过 stdin/stdout 收发 JSON-RPC 消息。
一条命令启动 MCP stdio
uvx proxmox-mcp-plus
或从源码运行 main.py,它负责依赖检查、注入 src 路径,然后调用 ProxmoxMCPServer(config_path).start()。stdio 模式下进程生命周期完全由客户端控制,因此代码里用 os._exit() 做信号退出,避免解释器收尾时与 SDK 的 stdin 工作线程死锁(src/proxmox_mcp/server.py 有详细注释)。
适用场景:客户端就在你的电脑上、服务器跑在本地。凭证可以放在 config.json 文件里,不必写进客户端 JSON 配置。
入口二:Streamable HTTP——把 MCP 服务化、远程化
当 MCP 客户端支持 Streamable HTTP 时(例如 Open WebUI 或跨机器的智能体),可以把服务器部署为常驻 HTTP 服务,监听 /mcp 端点。
Docker 启动方式(docker-compose.yml 中的 proxmox-mcp-http 服务):
export MCP_API_KEY="$(openssl rand -hex 32)"
docker compose --profile mcp-http up -d proxmox-mcp-http
客户端连接 http://<host>:8000/mcp,并携带 Authorization: Bearer <MCP_API_KEY>。
Streamable HTTP 的鉴权与安全控制
- Bearer 鉴权:由 src/proxmox_mcp/mcp_http_auth.py 中的中间件强制执行;未配置
MCP_API_KEY时服务直接拒绝启动(src/proxmox_mcp/server.py) - OAuth 浏览器门:可选开启 OAuth 授权码 + PKCE 流程,用户只需在同意页面输入一次 API Key,浏览器门实现见 src/proxmox_mcp/mcp_oauth_provider.py,OAuth 状态持久化在 PostgreSQL
- DNS 重绑定防护:支持
MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS白名单,防反向代理场景下的 DNS rebinding 攻击
适用场景:服务器跑在 Docker 容器或远端主机,多个客户端共享同一个 MCP 服务端点。
入口三:OpenAPI 桥——把 MCP 工具变成 REST API
第三条链路面向只懂 HTTP 的消费方:内部面板、Shell 脚本、监控、无代码工作流。它由 src/proxmox_mcp/openapi_proxy.py 实现,默认监听 8811 端口。
OpenAPI 桥内部如何桥接 stdio
这是架构上最有意思的一点:OpenAPI 桥并不是另写了一套工具调用逻辑,而是把 MCP stdio 服务器当作子进程包了起来。
看 src/proxmox_mcp/docker_entrypoint.py 的命令拼装:
return [
sys.executable, "-m", "proxmox_mcp.openapi_proxy",
"--host", host, "--port", port,
"--",
sys.executable, "-m", "proxmox_mcp.server", # MCP stdio 子进程
]
-- 之后的命令就是被拉起的 MCP stdio 服务器。FastAPI 应用通过 mcpo 库管理这个子进程的生命周期,并将其暴露为标准 OpenAPI 路由:
| 路由 | 用途 |
|---|---|
/openapi.json、/docs |
Swagger 文档与 Schema |
/livez、/readyz、/health |
存活/就绪/健康检查 |
/metrics |
Prometheus 格式指标 |
| 生成的工具路由 | 每个 MCP 工具对应一个 HTTP 端点 |
作业状态跨入口互通
OpenAPI 桥同时会直接挂载自己的 JobStore(src/proxmox_mcp/openapi_proxy.py),与 MCP 侧共享同一个 SQLite 作业库。因此经 MCP 创建的长任务,可以在 /jobs/{job_id} 上查询、轮询、取消、重试(src/proxmox_mcp/openapi_proxy.py)——这正是"三大入口协作"最直观的证据。
安全上,PROXMOX_API_KEY 是必填项,缺失时进程直接拒绝启动(src/proxmox_mcp/openapi_proxy.py),还支持按 IP 的限流。
# 一键验证 OpenAPI 服务
curl -f http://localhost:8811/livez
curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health
三大入口如何协作?一张图看懂
MCP 客户端(本地)──stdio──┐
远程 MCP 客户端──HTTP /mcp──┤
HTTP 脚本/面板──OpenAPI 桥──┤(桥内部再拉起一个 stdio 子进程)
▼
ProxmoxMCPServer(共享内核)
配置 · 目标注册 · 工具插件 · 命令策略
▼
JobStore(SQLite) + Proxmox VE API
协作的四个要点:
- 同一工具目录:三个入口看到的工具集合、参数校验、
approval_token审批策略完全一致,不存在"HTTP 入口绕过了 MCP 入口的安全检查"这种事 - 作业状态共享:MCP 工具返回
job_id,OpenAPI 的/jobs路由用同一个 SQLite 库读写,两个世界的长任务互相可见 - 凭证分层:
PROXMOX_API_KEY只保护 OpenAPI 桥,MCP_API_KEY只保护 Streamable HTTP,两者互不干扰,最终都汇聚到 Proxmox API Token 这一真实权限边界 - 部署可选组合:stdio 走 PyPI 包,HTTP 两个服务走 Docker(docker-compose.yml 中
proxmox-mcp-api与proxmox-mcp-http是两个独立服务,可单独启停、单独扩缩)
快速选型:我该用哪个入口?
| 你的场景 | 推荐入口 | 启动方式 |
|---|---|---|
| Claude Desktop / Cursor / VS Code 本地开发 | MCP stdio | uvx proxmox-mcp-plus |
| 远程 MCP 客户端、多客户端共享 | Streamable HTTP | docker compose --profile mcp-http up -d proxmox-mcp-http |
| Shell 脚本、面板、无代码自动化 | OpenAPI 桥 | docker compose up -d |
| 既要 MCP 又要 REST | 全部启用 | 两个 Docker 服务并存,共享配置卷 |
判断顺序很简单:客户端能不能本地拉子进程?能 → stdio。客户端是否原生支持 Streamable HTTP?是 → HTTP 模式。只认 REST → OpenAPI 桥。更多客户端配置示例可参考 docs/wiki/Integrations Guide.md 和 docs/agent-installation.md。
关键文件速查
| 模块 | 路径 |
|---|---|
| 本地启动入口 | main.py |
| MCP 服务器与 transport 分发 | src/proxmox_mcp/server.py |
| OpenAPI 桥(FastAPI + stdio 子进程) | src/proxmox_mcp/openapi_proxy.py |
| Docker 模式选择器 | src/proxmox_mcp/docker_entrypoint.py |
| HTTP Bearer 鉴权 | src/proxmox_mcp/mcp_http_auth.py |
| OAuth 浏览器门 | src/proxmox_mcp/mcp_oauth_provider.py |
| transport 配置模型 | src/proxmox_mcp/config/models.py |
| 持久化作业存储 | src/proxmox_mcp/services/jobs.py |
| 工具实现(VM/LXC/快照/备份等) | src/proxmox_mcp/tools/ |
理解了这套"一个内核、三副面孔"的架构后你会发现:新增一个工具只需在 src/proxmox_mcp/tools/ 下实现并注册插件,三个入口自动同步获得;而选择哪个入口部署,纯粹取决于你的客户端生态,不会带来任何功能差异。
