nandi-proxmox-mcp

NANDI Proxmox MCP

借助 140 多个用于自动化、监控和受控执行的工具，将 Proxmox 集群打造成 AI 驱动的平台。

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

nandi-proxmox-mcp 提供 Proxmox 清单、生命周期管理、存储、备份、网络、Firewall、访问控制、监控、SSH 诊断，以及受保护的远程和容器操作，同时保留生产集群所需的安全措施。

保持启用的功能

• 140 多个工具，涵盖节点、集群、QEMU、LXC、存储、备份、任务、网络、Firewall、资源池、访问控制、模板、监控和远程操作。
• 访问级别：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 传输，为受控远程部署提供 Streamable HTTP 传输。

所需权限

服务需要两种信任通道，并且有意保留两者：

• Proxmox API 令牌
  • 用于清单、生命周期管理、配置和管理端点。
  • 将 ACL 权限控制在最低限度：只授予实际启用的工具所需的角色。
• 对 Proxmox 主机的 SSH 批处理访问权限
  • pct exec、批量 SSH 诊断、只读主机诊断以及容器级 Docker 检查工具均需要此权限。
  • 这仍然是必要的，因为 Proxmox API 的覆盖范围无法替代基于主机端 pct 和 SSH 的诊断。

更多详情：docs/PERMISSIONS.md

破坏性操作确认

标记为破坏性的操作，只有在调用方发送 confirm=true 时才会执行。

示例：

• VM/容器停止、关机、重启、挂起、删除、迁移、快照回滚
• 可能更改集群状态的存储/网络/Firewall/访问控制写入操作
• pve_exec_in_container 等高级远程执行操作

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

人工审批

confirm=true 由 Agent 提供，而不是由你提供。读取到拒绝结果的模型可以直接重试并设置此标志，所以这项检查本身只能防止意外，无法防住有把握的 Agent——而且它从来不会询问你。

因此，这 47 个需要确认的工具也会告知客户端需要人工介入：

"_meta": { "anthropic/requiresUserInteraction": true }

在 Claude Code 2.1.199 及更高版本中，以这种方式标记的工具每次调用都会弹出提示——包括在 auto 和 bypassPermissions 模式下——并且无法通过 allow 规则或返回 allow 的 PreToolUse hook 预先批准。在 --permission-prompt-tool 下，自动审批会被转换为拒绝；Remote Control 会隐藏一键审批，并将你引导至完整提示。回答提示的操作员就是授权该操作的人。

有一点需要注意：这是在 2.1.229 上实际测得的行为，并非来自文档——提示仍会显示 "Yes, and don't ask again"，尽管文档称标记过的工具没有此选项。选择它会写入一条 allow 规则，但不会解除这道关卡——下次调用仍会弹出提示。因此，实际行为是正确的，只是按钮容易误导。不要把看不到该按钮当作防护已启用的信号；请连续调用受保护的工具两次进行验证。

有意不对启动和恢复来宾设置防护：这些操作会改变状态，但不会破坏任何东西；让人反感的防护，人们就会绕过。

setup 还会将匹配的 permissions.ask 规则写入 .claude/settings.json，以覆盖早于此注解的 Claude Code 版本。规则按 deny、ask、allow 的顺序评估——首个匹配项优先——因此，ask 规则在 bypassPermissions 模式下以及之后选择 "yes, don't ask again" 后仍然有效。对于手动配置而非通过 setup 配置的安装：

nandi-proxmox-mcp harden              # every configured instance
nandi-proxmox-mcp harden --name lab   # just one

这两种机制都仅适用于 Claude Code。在任何其他客户端中，防护机制是 confirm=true 和访问层级，因此请在该客户端中谨慎选择层级。

访问层级

• 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

本地配置文件

对于每个已配置的 Proxmox，Setup 都会写入一个凭据文件：.nandi-proxmox-mcp/<instance>.json；此外，还会在要求配置的每个客户端配置中添加注册项——默认情况下，Claude Code 使用 .mcp.json，VS Code 使用 .vscode/mcp.json，这两个文件都会写入。

凭据文件是唯一存放令牌的文件，并且已加入 gitignore。 未设置 NANDI_PROXMOX_CONFIG 时，服务会自动查找配置：如果只有一个已配置的实例，则自动使用；如果有多个实例，则会报错并列出它们，而不会猜测。

配置加载器现在会拒绝：

• 为空或格式错误的配置路径
• 超大配置文件
• 配置路径中的控制字符

快速开始

从未使用过 MCP？ 请从 docs/EMPEZAR.md 开始——这是一份分步骤指南（西班牙语）， 假设你之前不了解 MCP，并涵盖了创建 Proxmox 令牌的步骤；这一步最容易让人卡住。

首先，你需要从自己的 Proxmox 获取 API 令牌。运行以下命令会输出用于创建令牌的命令， 可直接粘贴到 Proxmox shell 中——它不会连接到任何地方：

npx nandi-proxmox-mcp bootstrap --tier read-only

然后进行引导式设置。默认情况下，这会为 Claude Code （.mcp.json）和 VS Code（.vscode/mcp.json）写入配置；如果任一文件 已存在，则会合并配置：

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

请从 --access-tier read-only 开始。服务内置的默认值是 full， 会开放所有具有破坏性的工具，包括任意命令执行； 传入此标志会将访问级别明确写入客户端配置，这样选择就清晰可见，而非隐式设置。确认设置可靠后，再提高访问级别。

选择特定客户端，或为任何其他 MCP 客户端打印配置片段：

npx nandi-proxmox-mcp setup --clients claude-code
npx nandi-proxmox-mcp setup --print-config          # writes nothing, safe to pipe

.mcp.json 只包含配置路径和策略设置，因此可以安全地提交和分享。你的 API 令牌保存在 .nandi-proxmox-mcp/config.json 中， 该文件已列入 gitignore。

使用环境变量直接运行：

$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 证书验证，连接可能遭受中间人攻击。此模式仅适用于实验环境。

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

安全责任

用户有责任：

• 仅允许可信操作人员访问
• 使用最小权限的 API 令牌和 SSH 密钥
• 避免在生产环境中使用不安全的 TLS
• 妥善保护底层基础设施

已实施的安全控制

• 访问级别（只读、读写执行、完整）
• 破坏性操作需要确认
• 同类操作需要人工审批，参见人工审批
• 输入验证和命令加固
• 速率限制和请求验证

HTTP 加固

HTTP 传输不执行任何身份验证。 POST /mcp 不会检查 Bearer 令牌、 API 密钥或客户端证书；以下控制措施仅作用于网络层。MCP_HOST 的默认值也 是 0.0.0.0，主机允许列表包含你配置的 Proxmox 和 SSH 主机。任何能 访问该端口并发送匹配 Host 标头的人，都能使用所有已注册工具——而在默认 PVE_ACCESS_TIER=full 下，这些工具包括破坏性工具和任意命令执行功能。

仅在可信网络上、经过需要身份验证的反向代理后，或通过 MCP_HOST 绑定到 127.0.0.1 时，才启用 MCP_TRANSPORT=http。默认的 stdio 传输不受影响： 它没有网络暴露面。

启用 MCP_TRANSPORT=http 时，服务会应用以下措施：

• 执行主机允许列表检查，包括通配符绑定保护
• 验证发送了 Origin 标头的请求的来源
• 设置明确的请求正文大小限制，并返回经过净化的 413 响应
• 对 /mcp 实施速率限制
• 设置请求、标头和 keep-alive 超时
• 设置 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、registry 和 marketplace 产物的描述符与版本是否同步
• 在日志中隐藏类似令牌、标头和密码的值
• 不向客户端返回堆栈跟踪或机密信息
• 在 CI 中设置 lint、typecheck、build、tests、metadata validation、descriptor sync、npm pack --dry-run 和 audit 检查门槛

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

发布流程

发布是自动的。 向 main 推送代码会运行 auto-release.yml，该工作流会读取自上一个 v* 标签以来的 Conventional Commit 提交主题所指示的版本升级级别，将新版本写入所有包含版本号的文件，提交 chore(release): vX.Y.Z，并推送标签。该标签会触发 release.yml 和下方的发布流程。

提交	升级级别
feat:	次要版本
fix:, perf:, revert:	补丁版本
feat!: 或 BREAKING CHANGE: 页脚	主要版本 — 严格遵循 semver，因此 0.x 会升至 1.0.0
chore:, docs:, test:, ci:, build:, style:, refactor:	不发布

如果推送中没有可发布的内容，流程会以绿色状态完成，并列出跳过的提交。手动运行工作流并设置 dry_run: true，即可在不发布的情况下查看版本和差异。

版本号存放在八处——清单、两个注册表描述文件、Marketplace 插件、两个文档示例和两个 TypeScript 字面量中。scripts/set-version.mjs 会写入所有这些位置，scripts/validate-package-metadata.mjs 会检查所有这些位置。添加第九处时，必须同时修改这两个脚本：写入器更新了某个文件，而验证器却忽略了它，就会导致 0.3.1 发布时仍宣称自己是 0.2.4。

标签生成后，发布顺序严格如下：

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 与注册表信息不一致。

如果发布中途失败，请重新运行 — gh workflow run release.yml --ref vX.Y.Z — 不要手动完成发布。每个发布步骤都会先检查目标位置，并跳过已存在的内容，因此重新运行只会完成尚未执行的部分。该任务会拒绝任何非标签引用，以及任何与 package.json 中版本号不一致的标签。

手动回退方案和故障排查：docs/RELEASE.md

开发

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

文档维护政策

本仓库遵循文档同步政策，并在评审中执行，而非通过 git 钩子执行。

没有预提交钩子。唯一通过自动化执行的检查位于 CI （.github/workflows/ci.yml）：它会重新生成 docs/TOOLS.md，并在存在任何偏差时令 构建失败。另请注意，如果机器上的 core.hooksPath 被重定向，仓库本地的 .git/hooks/pre-commit 将不会运行；这种情况很常见。

• 在结束一项 change、fix 或 refactor 前，评估是否需要更新 README.md、AGENTS.md 和 CONTRIBUTING.md。
• 如果某份文档与行为或流程影响相关，必须在同一变更集中更新。
• 如果无需更新，则必须明确说明 no-doc-change 的理由。
• 满足此检查要求后，任务才能视为已准备好提交。

文档

• docs/EMPEZAR.md — 如果你刚接触 MCP 服务，请从这里开始
• docs/CLAUDE_CODE_SETUP.md
• 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

注册表和 Marketplace

• 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。