NANDI Proxmox MCP

将您的 Proxmox 集群转变为 AI 驱动的平台，提供 140 多种用于自动化、监控和受控执行的工具。

由 NANDI Services 提供支持的 Proxmox VE 开源 MCP 服务器。

nandi-proxmox-mcp 公开了 Proxmox 的库存、生命周期、存储、备份、网络、防火墙、访问控制、监控、SSH 诊断以及受保护的远程/容器操作，且不会移除生产集群所需的必要安全防护措施。

保持启用的功能

• 涵盖节点、集群、QEMU、LXC、存储、备份、任务、网络、防火墙、资源池、访问控制、模板、监控和远程操作的 140 多种工具。

• 访问层级：read-only（只读）、read-execute（读写执行）、full（完全控制）。

• 模块拆分：PVE_MODULE_MODE=core|advanced。

• 工具过滤器：PVE_CATEGORIES、PVE_TOOL_BLACKLIST、PVE_TOOL_WHITELIST。

• 通过 confirm=true 实现破坏性操作的防护栏。

• 向后兼容的别名，例如 listNodes、getVMStatus、startVM、stopContainer。

• 用于 MCP 客户端的 stdio 传输，以及用于受控远程部署的可流式 HTTP 传输。

Related MCP server: ProxmoxMCP

所需权限

服务器需要两个信任通道，且两者均被有意保留：

• Proxmox API 令牌

  • 用于库存、生命周期、配置和管理端点。

  • 请保持 ACL 最小化：仅授予您实际启用的工具所需的角色。

• 到 Proxmox 主机的 SSH 批量访问权限

  • pct exec、批量 SSH 诊断和容器级 Docker 检查工具所必需。

  • 这是必要的，因为 Proxmox API 的覆盖范围无法替代主机端的 pct 和基于 SSH 的诊断。

更多详情：docs/PERMISSIONS.md

破坏性操作确认

标记为破坏性的操作除非调用者发送 confirm=true，否则不会执行。

示例：

• 虚拟机/容器的停止、关机、重启、挂起、删除、迁移、快照回滚

• 可能改变集群状态的存储/网络/防火墙/访问控制写入操作

• 高级远程执行，例如 pve_exec_in_container

当缺少确认时，服务器会返回结构化的 CONFIRMATION_REQUIRED 错误。此行为保持不变并得到强化。

访问层级

• read-only

  • 库存、状态、日志、指标和非变动性诊断。

• read-execute

  • 只读权限加上选定的执行/生命周期操作。

• full

  • 创建、更新、删除、迁移、恢复和管理员级操作。

PVE_MODULE_MODE=core 会隐藏高级工具，而不会重命名或从代码库中移除规范的工具 ID。

运行时配置

环境变量

必需：

• PROXMOX_HOST

• PROXMOX_USER

• PROXMOX_REALM

• PROXMOX_TOKEN_NAME

• PROXMOX_TOKEN_SECRET

• PROXMOX_SSH_HOST

• PROXMOX_SSH_USER

• PROXMOX_SSH_KEY_PATH

可选：

• PROXMOX_PORT 默认 8006

• PROXMOX_SSH_PORT 默认 22

• PROXMOX_ALLOW_INSECURE_TLS 默认 false

• PVE_ACCESS_TIER=read-only|read-execute|full

• PVE_MODULE_MODE=core|advanced

• PVE_CATEGORIES

• PVE_TOOL_BLACKLIST

• PVE_TOOL_WHITELIST

HTTP 传输：

• MCP_TRANSPORT=stdio|http

• MCP_HOST 默认 0.0.0.0

• MCP_PORT 默认 3000

• MCP_ALLOWED_HOSTS

• MCP_ALLOWED_ORIGINS

• MCP_RATE_LIMIT_WINDOW_MS

• MCP_RATE_LIMIT_MAX

• MCP_MAX_BODY_SIZE_BYTES

• MCP_HEADERS_TIMEOUT_MS

• MCP_REQUEST_TIMEOUT_MS

• MCP_KEEPALIVE_TIMEOUT_MS

• MCP_MAX_HEADERS_COUNT

本地配置文件

安装程序会写入 .nandi-proxmox-mcp/config.json 和 .vscode/mcp.json。

配置加载器现在会拒绝：

• 空或格式错误的配置路径

• 过大的配置文件

• 配置路径中的控制字符

快速入门

引导式设置：

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

使用环境变量直接运行：

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_USER="root"
$env:PROXMOX_SSH_KEY_PATH="$env:USERPROFILE\.ssh\id_ed25519"

npx nandi-proxmox-mcp run

安全模型与残余风险

此 MCP 服务器操作真实的 Proxmox 基础设施，并非沙盒环境。

信任假设

• 服务器部署在受信任的环境中

• 只有授权的操作员可以访问它

• 网络暴露受到控制（未公开暴露）

• 凭据得到安全管理

残余风险

以下风险是系统设计固有的：

• 特权操作
  完全访问层级和容器执行能力可以执行破坏性或系统级操作。

• SSH 执行边界
  远程命令执行依赖于 SSH，并继承目标系统的安全态势。

• 可选的不安全 TLS 模式
  启用后 (PROXMOX_ALLOW_INSECURE_TLS=true)，TLS 证书验证将被绕过，可能会使连接暴露于中间人 (MITM) 攻击。仅供实验室使用。

• 外部依赖同步
  包分发和列表可见性取决于 npm、MCP Registry 和市场传播时间。

安全责任

用户负责：

• 仅限受信任的操作员访问

• 使用最小权限的 API 令牌和 SSH 密钥

• 避免在生产环境中使用不安全的 TLS

• 正确保护底层基础设施

已实施的安全控制

• 访问层级（只读、读写执行、完全控制）

• 破坏性操作需要确认

• 输入验证和命令加固

• 速率限制和请求验证

HTTP 加固

当启用 MCP_TRANSPORT=http 时，服务器现在应用：

• 主机允许列表强制执行，包括通配符绑定保护

• 对发送 Origin 头的请求进行来源验证

• 明确的请求体大小限制和经过清理的 413 响应

• /mcp 上的速率限制

• 请求/头部/保持连接超时

• X-Content-Type-Options: nosniff

• Cache-Control: no-store

• 不包含堆栈跟踪的清理后的错误负载

健康/就绪端点：

• GET /health

• GET /ready

• POST /mcp

SSH 和命令执行加固

功能保持不变，但执行路径更加严格：

• 本地命令执行仍使用 spawn(..., { shell: false })

• SSH 主机/用户值无法通过 CLI 选项进行注入

• SSH 使用 BatchMode、IdentitiesOnly、公钥认证和明确的连接活跃度控制

• 输出缓冲区被限制以防止内存无限制增长

• dockerLogsInContainer 现在会对容器名称进行验证和 shell 转义，而不是插入原始用户输入

• 任意容器命令执行仅可通过已标记为破坏性的 pve_exec_in_container 流程进行，且需要确认

安全态势

仓库中的缓解措施：

• 锁定直接依赖版本，并对关键传递包使用 npm overrides

• 为 npm/包扫描器提供可验证的包元数据和仓库链接

• 对 npm、注册表和市场工件进行描述符/版本同步验证

• 在日志中屏蔽令牌/头部/密码类值

• 不向客户端返回堆栈跟踪或机密信息

• 用于 lint、类型检查、构建、测试、元数据验证、描述符同步、npm pack --dry-run 和审计的 CI 门控

威胁模型和残余风险：docs/THREAT_MODEL.md

发布流程

发布顺序严格如下：

1. npm run lint

2. npm run typecheck

3. npm run build

4. npm test

5. npm audit --include=dev --audit-level=moderate

6. npm ls express

7. npm ls path-to-regexp

8. npm pack --dry-run

9. npm pack

10. npm whoami

11. npm publish --access public

12. npm view nandi-proxmox-mcp version

13. mcp-publisher validate .mcp/server.json

14. mcp-publisher publish .mcp/server.json

基于标签的 release.yml 现在先发布 npm，然后再发布 MCP Registry 描述符，防止同一版本在 npm 和注册表之间出现偏差。

手动回退和故障排除：docs/RELEASE.md

开发

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run validate:release
npm pack --dry-run

文档维护策略

本仓库强制执行提交前文档同步门控。

• 在关闭 change、fix 或 refactor 之前，评估是否需要更新 README.md、AGENTS.md 和 CONTRIBUTING.md。

• 如果文档与行为或流程影响相关，则必须在同一变更集中进行更新。

• 如果不需要更新，则需要明确的 no-doc-change 理由。

• 在满足此门控之前，任务不被视为可提交状态。

文档

• docs/QUICKSTART.md

• docs/PERMISSIONS.md

• docs/SECURITY.md

• docs/THREAT_MODEL.md

• docs/RELEASE.md

• docs/TROUBLESHOOTING.md

• docs/TOOLS.md

• docs/MARKETPLACE_GO_LIVE.md

注册表和市场

• npm: https://www.npmjs.com/package/nandi-proxmox-mcp

• MCP Registry: https://registry.modelcontextprotocol.io/

• MCP Marketplace 列表: https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

许可证

MIT。请参阅 LICENSE。