AI导哈

Proxmox管理控制服务器

Proxmox-MCP是一个用于通过三层架构操作Proxmox VE的MCP服务器，提供类型化的Proxmox工具和显式的高风险操作访问。

  • by JoshuaGreeff
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 JoshuaGreeff/proxmox-mcp

使用说明

Proxmox MCP

Proxmox-MCP 是一种类型化的MCP服务器，用于通过三层一起使用来操作Proxmox VE：

  • 用于管理平面的Proxmox REST
  • Proxmox CLI通过SSH解决节点本地覆盖缺口
  • 为高风险的主机和客户机操作提供明确的shell和文件逃逸口

服务器是根据中提供的官方Proxmox API架构构建的 vendor/pve-docs.

该框架通过经过验证的域模块进行扩展。只有在实验室中进行端到端操作后，工作流程才会成为一种类型化的MCP工具。在验证之前，所有其他工具都可以通过通用的API/CLI/shell/file escape填充使用。

模块覆盖率的维护模式衍生路线图存在于 模块库存.md.

这是什么/不是什么

这是什么：

  • 一个真正的MCP服务器，带有由官方上游文档和模式支持的类型化Proxmox工具
  • 一个与客户端无关的控制界面，目前在stdio上工作，目标是使用OIDC进行远程HTTP部署
  • 一个以操作员为中心的服务器，它保持高风险的shell、文件和访客访问的明确性，而不是将其隐藏在模糊的工作流包装后面

这不是什么：

  • 围绕即席本地脚本的精简包装
  • 一个完全打包的生产平台，包含发布工件、托管文档和长期兼容性保证，已经锁定
  • 无策略的远程shell代理；高风险访问保持谨慎和可审计

项目状态

Proxmox-MCP 目前 Beta.

  • 本地 stdio 验证已到位，是主要的维护工作流程
  • http + oidc + file|vault 是预期的生产部署形状
  • 发布打包、更广泛的部署验证和更深入的运营成熟度仍在进行中

看 生产就绪 对于当前的支持边界和剩余差距。

社区/维护者文档

当前范围

  • 跨集群、节点、QEMU VM和LXC容器的库存
  • Proxmox生命周期、存储、网络、防火墙、备份、Ceph、SDN、用户、任务和控制台操作
  • 低级QEMU配置和模板原语以及云初始化代码片段工具
  • VM引导诊断
  • 一种用于无状态节点命令的便利节点终端运行器
  • 用于大型文本和二进制工具输出的工件/资源层
  • 通过验证原始REST访问 proxmox_api_call
  • 通过验证Proxmox CLI访问 proxmox_cli_run
  • 通过显式shell和文件访问 proxmox_shell_run, proxmox_file_read，以及 proxmox_file_write
  • 服务器拥有的用于长时间运行的作业

此仓库是一个真正的MCP服务器，而不是围绕本地脚本集合的包装器。

刀具表面

类型化工具：

这些是有意的低级通用Proxmox原语。该框架旨在公开MCP形状的Proxmox API表面，而不是预先构建的操作员工作流目录。

  • proxmox_inventory_overview
  • proxmox_cluster_status
  • proxmox_pci_mapping_list, proxmox_pci_mapping_get, proxmox_pci_mapping_create, proxmox_pci_mapping_update, proxmox_pci_mapping_delete
  • proxmox_node_list, proxmox_node_get, proxmox_node_action
  • proxmox_node_terminal_run
  • proxmox_vm_list, proxmox_vm_get, proxmox_vm_guest_agent_diagnose, proxmox_vm_action, proxmox_vm_agent_ping, proxmox_vm_agent_info, proxmox_vm_guest_exec
  • proxmox_vm_boot_diagnose
  • proxmox_vm_template_list, proxmox_vm_template_get
  • proxmox_storage_download_url
  • proxmox_vm_create, proxmox_vm_update_config, proxmox_vm_pci_attach, proxmox_vm_pci_detach, proxmox_vm_convert_to_template, proxmox_vm_clone, proxmox_vm_destroy
  • proxmox_cloud_init_snippet_list, proxmox_cloud_init_snippet_get, proxmox_cloud_init_snippet_put, proxmox_cloud_init_snippet_delete, proxmox_vm_cloud_init_dump
  • proxmox_lxc_list, proxmox_lxc_get, proxmox_lxc_action
  • proxmox_storage_list, proxmox_storage_get
  • proxmox_network_list
  • proxmox_firewall_get
  • proxmox_backup_jobs, proxmox_backup_start
  • proxmox_user_list
  • proxmox_ceph_status
  • proxmox_sdn_list
  • proxmox_task_list, proxmox_task_get
  • proxmox_console_ticket

完整性和逃生口：

  • proxmox_api_call
  • proxmox_cli_run
  • proxmox_shell_run
  • proxmox_file_read
  • proxmox_file_write
  • proxmox_bootstrap_node_access
  • proxmox_capabilities
  • job_get, job_wait, job_cancel, job_logs

一些工具现在将大文本或二进制输出作为MCP工件资源发布，而不是强制将所有内容内联到单个JSON响应中。这些文物暴露在 proxmox://artifacts/{artifactId}.

作业耐久性边界：

  • UPID支持的工作可以通过以下方式重新水合 job_get, job_wait, job_cancel，以及 job_logs 因为Proxmox保留了底层任务
  • 典型的例子是VM生命周期/配置突变、存储下载url作业、备份和其他返回Proxmox UPID的类型化REST突变
  • 进程运行执行路径，例如 proxmox_cli_run, proxmox_shell_run, proxmox_node_terminal_run，以及 proxmox_vm_guest_exec 延迟时保持流程本地
  • 此服务器不创建自己的持久本地作业数据库；仅在Proxmox已经拥有跨会话耐久性的情况下才提供跨会话持久性

在中跟踪了新VM诊断工具背后经过验证的引导/引导结果 靴子和鞋带.md.

配置

运行时启动表面仅为env。在实践中，这意味着您的MCP客户端配置或进程管理器环境是事实的来源。

支持的部署模式：

  • stdio
    • 本地维护人员工作流程
    • 可能仅对一次性环境使用显式本地引导
  • http
    • 远程MCP部署
    • 需要OIDC承载身份验证
  • both
    • 在一个进程中运行stdio和HTTP进行转换/测试

核心环境设置：

  • PROXMOX_HOST
  • PROXMOX_MCP_MODE=stdio|http|both
  • PROXMOX_MCP_AUTH_MODE=none|oidc
  • PROXMOX_MCP_SECRET_BACKEND=env|file|vault
  • PROXMOX_API_PORT
  • PROXMOX_DEFAULT_NODE
  • PROXMOX_DEFAULT_BRIDGE
  • PROXMOX_DEFAULT_VM_STORAGE
  • PROXMOX_DEFAULT_SNIPPET_STORAGE
  • PROXMOX_TLS_REJECT_UNAUTHORIZED

稳态运行时秘密：

  • 环境后端：
    • PROXMOX_API_TOKEN_USER
    • PROXMOX_API_TOKEN_REALM
    • PROXMOX_API_TOKEN_ID
    • PROXMOX_API_TOKEN_SECRET
    • PROXMOX_SHELL_SSH_USERNAME
    • PROXMOX_SHELL_SSH_PRIVATE_KEY 或 PROXMOX_SHELL_SSH_PRIVATE_KEY_PATH
    • PROXMOX_SHELL_SSH_EXPECTED_HOST_KEY
  • 文件后端：
    • PROXMOX_MCP_SECRET_FILE_PATH
  • vault后端：
    • PROXMOX_MCP_SECRET_VAULT_ADDR
    • PROXMOX_MCP_SECRET_VAULT_PATH
    • PROXMOX_MCP_SECRET_VAULT_TOKEN_ENV 或 VAULT_TOKEN

HTTP/OIDC设置：

  • PROXMOX_MCP_HTTP_HOST
  • PROXMOX_MCP_HTTP_PORT
  • PROXMOX_MCP_HTTP_PATH
  • PROXMOX_MCP_HTTP_PUBLIC_BASE_URL
  • PROXMOX_MCP_OIDC_ISSUER
  • PROXMOX_MCP_OIDC_AUDIENCE
  • PROXMOX_MCP_OIDC_JWKS_URL

仅适用于开发人员的本地引导程序：

  • PROXMOX_MCP_LOCAL_BOOTSTRAP=1
  • PROXMOX_BOOTSTRAP_SSH_USERNAME / PROXMOX_SSH_USERNAME
  • PROXMOX_BOOTSTRAP_SSH_PASSWORD / PROXMOX_SSH_PASSWORD

引导路径被有意限制为显式的本地stdio模式。它不是生产运行时模型。

Codex/MCP客户端设置

服务器仍然通过stdio工作。它从应用程序位置而不是当前工作目录解析供应商模式和应用程序相对默认值，因此客户端不需要设置 cwd 如果它通过绝对路径启动构建的入口点。

最小稳态stdio模式：

[mcp_servers.proxmox-mcp]
command = "C:\\Program Files\\nodejs\\node.exe"
args = ["C:\\path\\to\\Proxmox-MCP\\dist\\index.js"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 300

[mcp_servers.proxmox-mcp.env]
PROXMOX_HOST = "proxmox.example.internal"
PROXMOX_MCP_MODE = "stdio"
PROXMOX_MCP_AUTH_MODE = "none"
PROXMOX_MCP_SECRET_BACKEND = "env"
PROXMOX_API_TOKEN_USER = "proxmox-mcp"
PROXMOX_API_TOKEN_REALM = "pam"
PROXMOX_API_TOKEN_ID = "proxmox-mcp"
PROXMOX_API_TOKEN_SECRET = "replace-me"
PROXMOX_DEFAULT_NODE = "pve-example"

稳态路径的可选环境覆盖：

  • PROXMOX_API_PORT
  • PROXMOX_DEFAULT_NODE
  • PROXMOX_DEFAULT_BRIDGE
  • PROXMOX_DEFAULT_VM_STORAGE
  • PROXMOX_DEFAULT_SNIPPET_STORAGE
  • PROXMOX_TLS_REJECT_UNAUTHORIZED
  • PROXMOX_SHELL_SSH_* 如果要启用shell/CLI/文件转义填充

远程HTTP模式是生产目标。请参阅：

所有支持的启动覆盖都属于MCP客户端环境块或监督进程环境。没有旧版配置文件回退。

Proxmox配置

可重复的Proxmox配置现在属于MCP服务器，而不是存储库本地操作员包装器。

删除了旧的SSH繁重的配置脚本，因为它们复制了类型化的MCP表面，并偏离了当前仅支持env的启动模型。如果一个工作流是可重用的，并且面向Proxmox，那么预期的路径是通过MCP来执行它，并在需要时改进键入的工具。

经过验证的配置和模板原语是：

  • proxmox_storage_download_url
    • 使用记录的REST端点将图像或模板工件下载到Proxmox存储中
  • proxmox_vm_create
    • 从低级配置参数创建QEMU VM
  • proxmox_vm_update_config
    • 从低级配置参数（如磁盘、云初始化、串行控制台、气球或SSH密钥）更新QEMU VM配置
  • proxmox_vm_pci_attach
    • 首先使用REST通过类型化的QEMU配置界面连接原始主机PCI设备或集群PCI映射 qm set 仅适用于已知的纯生根 hostpci 案例
  • proxmox_vm_pci_detach
    • 分离a hostpci 通过类型化的QEMU配置界面插入插槽，具有相同的显式REST优先传输行为
  • proxmox_vm_convert_to_template
    • 将现有VM转换为模板
  • proxmox_vm_clone
    • 使用低级克隆参数克隆VM或模板，例如 newid, full, storage，以及 target
  • proxmox_vm_destroy
    • 通过记录的REST端点销毁VM或模板
  • proxmox_cloud_init_snippet_*
    • 在支持Proxmox代码段的存储上管理代码段文件
  • proxmox_vm_cloud_init_dump
    • 生成的转储 user, network，或 meta 用于调试的云初始化

重要区别：

  • 模板引导属于存储在Proxmox代码段存储器上的云初始化代码段内容
  • 特定于操作员的克隆定制属于低级VM配置和云初始化输入，而不是存储库本地包装器脚本
  • proxmox_node_terminal_run 是无状态节点命令的便利工具，而 proxmox_shell_run 仍然是通用的高风险弹壳逃生口

对于这些工作流的实时验证，请使用中的直接stdio线束 docs/direct-mcp-testing.md.

此仓库中唯一有意保留的独立脚本是主机本地维护者助手，例如：

  • Hyper-V外部实验室创建/删除
  • 供应商文档刷新和摘要生成

这些位于MCP产品表面之外，因为它们在维护人员工作站或仓库维护输入上运行，而不是通过服务器在托管的Proxmox资源上运行。

发展

分支和推广流程：

  • main 是准备生产的分支机构吗
  • dev 是集成和预发布分支
  • 正常的工作应该从 dev 变成短命 feature/* 分支，然后合并回 dev
  • 发布推广应该通过合并来实现 dev 进入 main
  • 紧急修复可能针对 main 通过 hotfix/* 分支，但必须重新合并到 dev
  • 两个分支都有分支保护，但所有者/管理员旁路仍可用于紧急情况

看 分支工作流程 对于维护者流程。

npm install
npm run check
npm run test
npm run build

在stdio模式下本地运行服务器：

npm run dev

运行管理CLI：

npm run admin -- status --secret-backend env

运行构建的入口点：

node C:\path\to\Proxmox-MCP\dist\index.js

实时集成测试是环境门控的：

$env:ENABLE_LIVE_PROXMOX_TESTS="1"
npm run test:live

回购布局

  • src/：服务器、配置加载程序、策略实施、API客户端、SSH/WinRM传输和面向域的MCP工具注册
  • src/tools/：MCP工具注册按Proxmox域分组，每个注册都有一个本地维护者README
  • tests/：单元和现场测试覆盖率
  • docs/proxmox/：来自官方Proxmox文档的本地注释
  • vendor/pve-docs/：vendored上游Proxmox文档和API架构
  • scripts/：用于文档刷新和外部实验室主机设置的可复制助手脚本
  • docs/framework-architecture.md：框架层和验证模块规则的维护者指南
  • docs/direct-mcp-testing.md：直接stdio MCP验证的维护人员指南，无需依赖编辑器MCP重新加载

文档

  • docs/proxmox/README.md
  • docs/proxmox/api-programming-guide.md
  • docs/proxmox/command-map.md
  • docs/proxmox/api-summary.json
  • docs/proxmox/module-inventory.md
  • docs/proxmox/module-inventory.json
  • docs/direct-mcp-testing.md
  • docs/branching.md
  • docs/production-readiness.md
  • docs/getting-started.md
  • docs/deployment.md
  • docs/security.md
  • docs/operations.md

项目卫生

公共仓库应包含可复制的代码和文档，而不是实时配置、审计日志、生成的构建输出、ISO文件或本地密钥。如果您正在准备发布，请验证启动说明是否仍指向MCP客户端 config.toml 仅限于环境配置。

相关 MCP