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 传输。

所需权限

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

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

发布流程

发布顺序严格如下：

npm run lint
npm run typecheck
npm run build
npm test
npm audit --include=dev --audit-level=moderate
npm ls express
npm ls path-to-regexp
npm pack --dry-run
npm pack
npm whoami
npm publish --access public
npm view nandi-proxmox-mcp version
mcp-publisher validate .mcp/server.json
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 理由。
在满足此门控之前，任务不被视为可提交状态。

文档

注册表和市场

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。

nandi-proxmox-mcp