🚀 Proxmox MCP Server (Node.js Edition)

Proxmox MCP 服务（Node.js 版）

基于 Node.js 的模型上下文协议（MCP）服务，用于管理 Proxmox VE 虚拟机管理程序：节点、QEMU 虚拟机和 LXC 容器，并支持配置权限级别以及导出 Terraform/OpenTofu。

致谢

基于 canvrno/ProxmoxMCP 的原始 Python 实现。此 Node.js 版本保留了相同的核心功能，同时新增了可配置的权限管理以及 Terraform/OpenTofu 生成。

功能

• 两种权限级别：默认只读；破坏性操作需要显式选择启用（PROXMOX_ALLOW_ELEVATED=true）
• 节点、虚拟机和容器管理：状态、生命周期（启动/停止/重启/关机/暂停）、创建、克隆、调整大小、删除、迁移、转换为模板
• 任务跟踪：通过 UPID 读取任意任务（也可选择等待任务完成），以便变更操作确认实际执行完毕
• 客户机 Agent 集成：运行命令并读取其标准输出/退出代码，以及发现正在运行的虚拟机的实际 IP 地址
• 快照和备份：创建、列出、回滚、删除
• 磁盘和网络配置：添加、调整大小、移动和移除磁盘、挂载点及网络接口
• Cloud-init、历史指标（RRD），以及对资源池、HA 资源和防火墙规则的只读监控
• Terraform/OpenTofu 导出：根据现有虚拟机和容器生成 HCL（含 import 块），将其纳入 IaC 管理而不重新创建
• 结构化输出：工具会在 Markdown 文本之外返回机器可读的 structuredContent，便于 Agent 基于数据串联操作
• MCP 资源（proxmox://nodes、proxmox://vms、proxmox://storage）和提示词（资源配置、健康检查、权限诊断）
• 安全措施：可选的 TLS 验证、节点/VMID 允许列表，以及阻止删除受保护客户机的保护标志检查
• 基于官方 MCP SDK 构建

安装

前提条件

• Node.js 20+ 和 npm
• Proxmox VE 服务端及 API 令牌（参见 API 令牌设置）

设置

克隆并安装：

git clone https://github.com/gilby125/mcp-proxmox.git
cd mcp-proxmox
npm install

或者通过 npx 运行，无需克隆：

PROXMOX_HOST=your-proxmox-ip PROXMOX_TOKEN_VALUE=your-token-secret npx mcp-proxmox

或者使用 Docker（MCP 通过标准输入/输出通信，因此请使用 -i 并保持容器运行）：

docker build -t mcp-proxmox .
docker run -i --rm \
  -e PROXMOX_HOST=your-proxmox-ip \
  -e PROXMOX_TOKEN_VALUE=your-token-secret \
  mcp-proxmox

配置

服务完全通过环境变量进行配置：

变量	必填	默认值	说明
PROXMOX_HOST	是	—	Proxmox IP 地址或主机名
PROXMOX_TOKEN_VALUE	是	—	API 令牌密钥
PROXMOX_USER	否	root@pam	令牌所属用户
PROXMOX_TOKEN_NAME	否	mcpserver	API 令牌 ID
PROXMOX_PORT	否	8006	Proxmox API 端口
PROXMOX_ALLOW_ELEVATED	否	false	设置为 true 以启用写入/破坏性工具
PROXMOX_VERIFY_TLS	否	false	设置为 true 以验证 Proxmox TLS 证书（需使用 CA 签名的证书）
PROXMOX_NODE_ALLOWLIST	否	—	服务可操作的节点名称，以逗号分隔；留空表示不限制
PROXMOX_VMID_ALLOWLIST	否	—	服务可操作的 VMID，以逗号分隔；留空表示不限制

有两种提供这些变量的方式：

选项 1：在 MCP 客户端配置中使用 env 块（推荐）

对于 Claude Desktop，请编辑配置文件（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Linux：~/.config/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-proxmox/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-ip",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-server",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_ALLOW_ELEVATED": "false"
      }
    }
  }
}

编辑后重启客户端，然后提问“列出我的 Proxmox 虚拟机”进行测试。

选项 2：在安装目录的上级目录中使用 .env 文件

服务会从相对于 index.js 的 ../.env 加载 .env，也就是克隆仓库所在目录的上级目录（将文件放在仓库之外，以免提交密钥）：

/home/user/
├── .env             <- environment file goes here
└── mcp-proxmox/
    └── index.js     <- loads ../.env from here

# /home/user/.env
PROXMOX_HOST=your-proxmox-ip-or-hostname
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=mcp-server
PROXMOX_TOKEN_VALUE=your-token-secret
PROXMOX_ALLOW_ELEVATED=false

Proxmox API 令牌设置

1. Proxmox Web UI -> Datacenter -> Permissions -> API Tokens -> Add
2. 选择用户（例如 root@pam）和令牌 ID（例如 mcp-server）
3. 立即复制密钥——它只会显示一次
4. 将令牌 ID 用作 PROXMOX_TOKEN_NAME，将密钥用作 PROXMOX_TOKEN_VALUE

权限：基本（只读）模式只需最少的令牌权限即可运行。提升权限模式需要包含 Sys.Audit、VM.Monitor、VM.Console、VM.Allocate、VM.PowerMgmt、VM.Snapshot、VM.Backup、VM.Config.*、Datastore.Audit、Datastore.Allocate 的角色，具体取决于你使用的工具。

权限级别

基本模式（PROXMOX_ALLOW_ELEVATED=false，默认值）仅允许读取操作：列出节点、VM、容器、存储、集群状态和模板，以及生成 Terraform。

提升权限模式（PROXMOX_ALLOW_ELEVATED=true）还会启用写入工具，可创建、修改和永久删除 VM、容器、快照、备份、磁盘和网络接口，并在来宾系统中执行命令。只有在了解并接受这些风险后才启用。

可用工具

只读（始终可用）

工具	描述
proxmox_get_nodes	列出集群节点及其状态和资源
proxmox_get_node_status	节点详细状态（需要提升权限和 Sys.Audit）
proxmox_get_vms	列出 VM/容器，可按节点和类型筛选
proxmox_get_vm_status	单个 VM/容器的详细状态
proxmox_get_storage	列出存储池及其使用情况
proxmox_get_cluster_status	集群健康状况概览
proxmox_list_templates	列出存储上的 LXC 模板
proxmox_get_next_vmid	下一个可用的 VM/容器 ID
proxmox_get_vm_config	VM/容器的完整配置（核心数、内存、磁盘、网络、cloud-init）
proxmox_get_task_status	根据 UPID 查询任务状态；可选择等待任务完成
proxmox_whoami	令牌认证的身份及其有效权限
proxmox_get_rrd_data	历史 CPU/内存/磁盘/网络时间序列数据（节点或来宾系统）
proxmox_get_pools	资源池及其成员
proxmox_get_ha_resources	高可用资源及其期望状态
proxmox_get_firewall_rules	集群/节点/来宾系统级别的防火墙规则
proxmox_generate_terraform	根据现有来宾系统生成 Terraform/OpenTofu HCL

提升权限（需要 PROXMOX_ALLOW_ELEVATED=true）

类别	工具
创建	proxmox_create_vm、proxmox_create_lxc
生命周期	proxmox_start_*、proxmox_stop_*、proxmox_reboot_*、proxmox_shutdown_*、proxmox_pause_vm、proxmox_resume_vm
克隆 / 调整大小 / 删除	proxmox_clone_*、proxmox_resize_*、proxmox_delete_*
快照	proxmox_create_snapshot_*、proxmox_list_snapshots_*、proxmox_rollback_snapshot_*、proxmox_delete_snapshot_*
备份	proxmox_create_backup_*、proxmox_list_backups、proxmox_restore_backup_*、proxmox_delete_backup
磁盘	proxmox_add_disk_vm、proxmox_add_mountpoint_lxc、proxmox_resize_disk_*、proxmox_remove_disk_vm、proxmox_remove_mountpoint_lxc、proxmox_move_disk_*
网络	proxmox_add_network_*、proxmox_update_network_*、proxmox_remove_network_*
迁移 / 模板	proxmox_migrate_vm、proxmox_convert_to_template
Cloud-init	proxmox_set_cloudinit（QEMU）
来宾系统命令执行 / IP 地址	proxmox_execute_vm_command、proxmox_get_guest_ips（通过来宾代理用于 QEMU）

带有 _* 后缀的工具同时提供 _vm（QEMU）和 _lxc（容器）变体。

proxmox_execute_vm_command 默认会轮询来宾代理（wait: true），并返回命令的 stdout、stderr 和退出代码；传入 wait: false 则只返回 PID。proxmox_migrate_vm 和其他长时间运行的操作会返回任务 UPID——将其传给 proxmox_get_task_status（并设置 wait: true）以确认操作完成。

Terraform/OpenTofu 导出

proxmox_generate_terraform 会读取现有 VM 和容器的实时配置，并为 bpg/proxmox Provider 生成 HCL，其中包含 import 块，使 terraform plan / tofu plan 能接管正在运行的来宾，而不是重新创建它们。

参数（均为可选）：

• node — 仅导出此节点上的来宾
• vmid — 导出单个 VM/容器
• type — qemu、lxc 或 all（默认值）
• include_provider — 包含 terraform {} / provider {} 框架代码（默认值为 true）

提示词示例：“为节点 pve1 上的 VM 100 生成 terraform”。然后：

# save the output as main.tf
terraform init   # or: tofu init
export TF_VAR_proxmox_api_token='user@realm!tokenid=uuid'
terraform plan   # import blocks adopt the existing guests

生成器无法映射的选项会列在各资源块的注释中。LXC 资源包含 ignore_changes = [operating_system] 生命周期块，因为 Proxmox 不会记录源模板，因此占位符 template_file_id 不会导致已接管的容器被强制替换。

资源和提示词

除了工具，服务还提供 MCP 资源，以 JSON 格式浏览只读集群状态：proxmox://nodes、proxmox://vms 和 proxmox://storage；以及适用于常见工作流的 MCP 提示词：provision_lxc、health_check 和 diagnose_permissions。

结构化输出

每个工具都会返回供人阅读的 Markdown 摘要，以及供程序使用的 structuredContent 对象。例如，proxmox_get_vms 会返回 { count, vms: [{ vmid, name, type, node, status, cpu, mem, maxmem, ... }] }。不理解 structuredContent 的客户端只会呈现文本。

测试

# Unit tests (no Proxmox server needed)
npm test

# Live read-only integration test (needs a configured Proxmox connection)
node test-basic-tools.js

# Live workflow tests — CREATES AND DELETES real resources; needs elevated mode
node test-workflows.js [--dry-run] [--interactive] [--workflow=lxc|disk|snapshot]

有关工作流测试的详细信息，请参阅 TEST-WORKFLOWS.md。

开发

npm install
npm start        # run the server
npm run dev      # run with auto-reload
npm test         # unit tests

# Poke the server directly over stdio
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js

持续集成通过 GitHub Actions（.github/workflows/ci.yml）在 Node 20 和 22 上运行 npm test。

已知限制

• 默认关闭 TLS 验证，以便服务开箱即用地兼容 Proxmox 的自签名证书。如果你使用 CA 签名证书，请设置 PROXMOX_VERIFY_TLS=true。验证关闭时，请勿将服务连接到不受信任的网络。
• proxmox_execute_vm_command、proxmox_get_guest_ips 和 proxmox_set_cloudinit 仅适用于 QEMU VM。Proxmox HTTP API 没有适用于 LXC 容器的 exec/agent 端点，因此对 type: lxc 执行命令会返回明确的“不支持”消息；请改用 SSH，或在主机上使用 pct exec。

故障排除

• “Could not load .env file”警告 — 如果你通过 MCP 客户端的 env 块传入变量，则此警告无害；否则，请将 .env 放在仓库的父目录中（在 mcp-proxmox 内运行 ls ../.env）。
• 连接被拒绝 / 超时 — 检查 PROXMOX_HOST、PROXMOX_PORT（默认值为 8006）和防火墙规则。
• 401 Unauthorized — 检查 PROXMOX_USER 格式（root@pam）、PROXMOX_TOKEN_NAME，以及 PROXMOX_TOKEN_VALUE 中的密钥是否完整。
• “Requires Elevated Permissions” — 设置 PROXMOX_ALLOW_ELEVATED=true，并为令牌授予上文列出的角色。
• QEMU 命令执行失败 — 在 VM 内安装并启用 QEMU guest agent（apt install qemu-guest-agent），在 VM 选项中启用它，然后重启 VM。

许可证

MIT — 参见 LICENSE。