使用说明

Proxmox MCP服务器（Node.js版）

基于Node.js的模型上下文协议（MCP）服务器，用于管理Proxmox VE管理程序：节点、QEMU VM和LXC容器，具有可配置的权限级别和Terraform/OpenTofu导出。

鸣谢

基于Python的原始实现 canvrno/ProxmoxMCP这个Node.js版本保留了相同的核心功能，同时添加了可配置的权限管理和Terraform/OpenTofu生成。

特性

两个权限级别：默认为只读；破坏性行动需要明确的选择加入(PROXMOX_ALLOW_ELEVATED=true)
节点、VM和容器管理：状态、生命周期（启动/停止/重新启动/关闭/暂停）、创建、克隆、调整大小、删除、迁移、转换为模板
任务跟踪：通过UPID读取（并可选地等待）任何任务，这样变异操作就可以确认它们确实完成了
客户机代理集成：运行命令并读取其stdout/exit代码，并发现正在运行的VM的真实IP地址
快照和备份：创建、列出、回滚、删除
磁盘和网络配置：添加、调整大小、移动和删除磁盘、装载点和网络接口
云初始化、历史指标（RRD）以及池、HA资源和防火墙规则的只读可观察性
Terraform/OpenTofu导出：生成HCL（含 import 从现有的VM和容器中提取块，将其纳入IaC，而无需重新创建
结构化输出：工具返回机器可读 structuredContent 在Markdown文本旁边，这样代理就可以链接数据
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通过stdio进行通信，因此运行时附带 -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`	是	-	neneneba 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 VM”进行测试。

选项2:安装父目录中的.env文件

服务器加载 .env 来自 ../.env 相对于 index.js --即克隆仓库上方的目录（保存在仓库外部，因此无法提交机密）：

/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令牌设置

Proxmox web UI->数据中心->权限->API令牌->添加
选择一个用户（例如。 root@pam)以及令牌ID（例如。 mcp-server)
立即复制秘密——它只显示一次
将令牌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`	列出虚拟机/容器，可按节点和类型进行筛选
`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/容器的完整配置（核心、内存、磁盘、网络、云初始化）
`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`
云初始化	`proxmox_set_cloudinit` （QEMU）
客座执行官/IP	`proxmox_execute_vm_command`, `proxmox_get_guest_ips` （QEMU通过客户代理）

工具与a _* 后缀存在于 _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和容器的实时配置，并为发出HCL bpg/proxmox 供应商，包括 import 块所以 terraform plan / tofu plan 采用跑步的客人，而不是重新创造他们。

参数（全部可选）：

node --仅导出此节点上的来宾
vmid --导出单个VM/容器
type — qemu, lxc，或 all （默认）
include_provider --包括 terraform {} / provider {} 脚手架（默认 true)

示例提示：“在节点pve1上为VM 100生成地形”。然后：

# 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]

看测试工作流.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

持续集成运行 npm test 通过GitHub操作在Node 20和22上(.github/workflows/ci.yml).

已知限制

TLS验证默认为关闭，因此服务器可以开箱即用Proxmox的自签名证书。集 PROXMOX_VERIFY_TLS=true 当您拥有CA签名的证书时。不要将服务器指向禁用验证的不受信任的网络。
proxmox_execute_vm_command, proxmox_get_guest_ips，以及 proxmox_set_cloudinit 仅适用于QEMU虚拟机。ProxmoxHTTP API没有LXC容器的exec/agent端点，因此命令执行返回一个明确的“不支持”消息 type: lxc --使用SSH或 pct exec 而是在主机上。

故障排除

“无法加载.env文件”警告——如果通过MCP客户端传递变量，则无害 env 阻断；否则放 .env 在repo的父目录中(ls ../.env 从内部 mcp-proxmox).
连接被拒绝/超时--检查 PROXMOX_HOST, PROXMOX_PORT （默认8006）和防火墙规则。
401未经授权--检查 PROXMOX_USER 格式(root@pam), PROXMOX_TOKEN_NAME，而其中的秘密 PROXMOX_TOKEN_VALUE 已完成。
“需要提升权限”--设置 PROXMOX_ALLOW_ELEVATED=true 并授予令牌上面列出的角色。
QEMU命令执行失败--在VM内安装并启用QEMU来宾代理(apt install qemu-guest-agent)，在VM选项中启用它，然后重新启动VM。

许可证

麻省理工学院——见许可证.

使用说明

Proxmox MCP服务器（Node.js版）

鸣谢

特性

安装

先决条件

设置

配置

选项1:MCP客户端配置中的env块（推荐）

选项2:安装父目录中的.env文件

Proxmox API令牌设置

权限级别

可用工具

只读（始终可用）

高架（要求 PROXMOX_ALLOW_ELEVATED=true)

Terraform/OpenTofu出口

资源和提示

结构化输出

测试

发展

已知限制

故障排除

许可证

相关 MCP

Terraform Registry MCP 服务器

CDK最佳实践服务

Terraform MCP 服务器

GCP资源管理工具

基础设施即代码记忆服务器

Terraform执行服务

高架（要求 `PROXMOX_ALLOW_ELEVATED=true`)