Proxmox Mcp

Proxmox MCP 服务

简易 Proxmox MCP

用于管理 Proxmox VE 的 MCP 服务

50 个工具 — 节点、QEMU 虚拟机、LXC 容器、存储、集群、快照。

为什么选择它？

• 单一镜像，支持多架构 — 运行 docker run ghcr.io/akmalovaa/proxmox-mcp:latest 即可
• 只需环境变量 — 无配置文件、无数据库、无状态
• 默认只读 — 破坏性操作由显式设置的 PROXMOX_RISK_LEVEL 控制
• 支持 stdio 或 Streamable HTTP — 只差一个环境变量；默认使用 stdio，HTTP 绑定到回环地址
• 代码库精简 — 基于 Proxmoxer 的轻量封装，无配置文件、无数据库、无状态
• 直接输出原始 JSON — 无格式化、无表情符号；大模型可获取干净的数据
• 错误信息易读 — 403、主机无响应或层级限制都会以句子说明，而不是堆栈跟踪

快速开始

镜像： ghcr.io/akmalovaa/proxmox-mcp:latest（支持多架构：amd64 + arm64）。

1. 在 shell 配置文件中导出凭据（~/.zprofile、~/.zshrc 或 ~/.bashrc）：

# token auth (recommended — see "Least privilege" for the user and role to give it):
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=mcp@pve
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# or password auth:
# export PROXMOX_USER=root@pam
# export PROXMOX_PASSWORD=your-password

# optional:
export PROXMOX_RISK_LEVEL=read

重新加载：source ~/.zprofile（或重启 shell）。

2. 添加到 ~/.claude/settings.json（Claude Code）或 claude_desktop_config.json（Claude Desktop）：

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_PASSWORD",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

或使用令牌认证：

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

不带值的 docker run -e VAR 会传递主机环境变量，因此配置文件中无需包含密钥。重启客户端后，即可使用 32 个只读 Proxmox 工具（提高 PROXMOX_RISK_LEVEL 后可用更多工具）。

使用密码认证时，将令牌变量替换为 PROXMOX_PASSWORD。

注意： macOS 上的 Claude Desktop 通过 launchd 启动，不会继承 ~/.zprofile/~/.zshrc。请将导出语句放入 ~/.zshenv，或者改为在配置中使用内联 "env": { ... } 块。

配置

所有设置均为环境变量 — 可在 shell 配置文件中设置，通过 docker run -e 内联传入，或在 MCP 客户端的 env 块中声明。

变量	默认值	描述
PROXMOX_HOST	—	Proxmox 主机（IP 或主机名）
PROXMOX_USER	root@pam	API 用户
认证	—	令牌 或 密码 — 见下文
PROXMOX_PORT	8006	API 端口
PROXMOX_VERIFY_SSL	false	验证 TLS 证书
PROXMOX_TIMEOUT	15	每次 API 请求的等待秒数
PROXMOX_RISK_LEVEL	read	read / lifecycle / all — 见风险级别
PROXMOX_TOOLS_ALLOW	—	除风险级别允许的工具外，额外注册的工具名称（逗号分隔）
PROXMOX_REDACT_SECRETS	true	在响应中隐藏 cipassword / sshkeys

传输设置使用 PROXMOX_MCP_ 前缀 — 见 Streamable HTTP。

身份验证：令牌 或 密码

二选一。如果两者都已设置，则令牌优先。

令牌（推荐）：

export PROXMOX_USER=mcp@pve
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

只设置这对配置中的一项会导致启动错误，而不会静默回退到密码。以前，PROXMOX_TOKEN_NAME 中的拼写错误会导致程序悄悄以 PROXMOX_USER 的身份运行。

密码（备用）：

export PROXMOX_PASSWORD=your-password

最小权限

MCP 服务可能会被根据其未编写的文本行事的模型访问，因此应为它单独创建用户和令牌，而不要使用 root@pam。在 Proxmox 主机上：

# a user that is not root, with a role that matches the risk level you plan to run
pveum user add mcp@pve
pveum acl modify / --users mcp@pve --roles PVEAuditor          # read
# pveum acl modify / --users mcp@pve --roles PVEVMAdmin        # lifecycle / all

# a token for that user. Privilege Separation ON (the default) means the token starts
# with no rights at all, so grant it the same role explicitly:
pveum user token add mcp@pve mcp --privsep 1
pveum acl modify / --tokens 'mcp@pve!mcp' --roles PVEAuditor

检查令牌最终实际获得了哪些权限：

pveum user permissions mcp@pve --token mcp

PVEAuditor 涵盖全部 32 个只读工具。在 /vms 上设置 PVEVMAdmin 可添加虚拟机生命周期管理和快照功能；migrate_vm 还需要在目标节点上拥有 VM.Migrate 权限，而 clone_vm 需要在目标存储上拥有 Datastore.AllocateSpace 权限。如果服务只应查看集群的一部分，请缩小 ACL 路径范围（/vms/101、/pool/homelab）。

root@pam 仍然可用，也是本地快速查看时最省事的选择，只是不应让它一直运行。

风险级别

PROXMOX_RISK_LEVEL 控制哪些工具可用。高于当前级别的工具不会注册，因此不会出现在 MCP 客户端的工具列表中：

级别	工具数	新增内容
read （默认）	32	只读工具
lifecycle	46	+ 启动 / 停止 / 重启 / 挂起 / 克隆 / 迁移 / 创建快照
all	50	+ 删除快照 / 回滚快照

每次提升权限的调用也会在调用时重新检查，并记录到 stderr（ALLOW / DENY + 工具 + 层级）。

客户端无法以其他方式获知当前级别——缺失的工具看起来和从未编写过的工具没有区别——因此 get_server_info 会报告当前级别，以及版本和工具数量。

对于只服务于某个特定 Agent 的部署，PROXMOX_TOOLS_ALLOW 可在当前层级范围内进一步缩小工具范围：

export PROXMOX_TOOLS_ALLOW=list_nodes,list_containers,get_container_status,get_cluster_resources

不存在的名称会导致启动错误，因此拼写错误不会悄悄删减工具列表。除非有特殊原因，否则请将 get_server_info 保留在列表中——客户端通过它了解列表中其他工具的含义。

响应格式

资源清单列表（list_nodes、list_vms、list_containers、get_cluster_resources）会返回每行的精简字段：标识、状态、运行时间、CPU 和内存。被省略的是每秒 I/O 计数器和 PSI 压力指标——它们是真实数据，但对分诊决策没有帮助，且数据量是保留内容的好几倍。传入 verbose=true 可获取未经处理的行。

写入工具返回的是 Proxmox 接受的任务，而不是已完成的结果：

{"state":"accepted","operation":"start_vm","node":"pve","vmid":101,
 "upid":"UPID:pve:...","poll_with":"get_task_status"}

cipassword 和 sshkeys 在所有位置都会替换为 ***redacted***，同时保留键名，以便模型仍能判断 cloud-init 是否已配置。设置 PROXMOX_REDACT_SECRETS=false 可获取原始值。

Streamable HTTP

stdio 仍是默认传输方式，也是你本机上的 MCP 客户端应使用的方式。对于共享部署——例如集群中的容器，或多个客户端共用一个 URL——设置传输方式，其他内容无需更改：

docker run --rm -p 8000:8000 \
  -e PROXMOX_HOST -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  -e PROXMOX_MCP_TRANSPORT=streamable-http \
  -e PROXMOX_MCP_HOST=0.0.0.0 \
  -e PROXMOX_MCP_ALLOWED_HOSTS=proxmox-mcp.example.com \
  ghcr.io/akmalovaa/proxmox-mcp:latest

变量	默认值	描述
PROXMOX_MCP_TRANSPORT	stdio	stdio 或 streamable-http
PROXMOX_MCP_HOST	127.0.0.1	绑定地址——在容器中使用 0.0.0.0
PROXMOX_MCP_PORT	8000	端口
PROXMOX_MCP_PATH	/mcp	端点路径
PROXMOX_MCP_JSON_RESPONSE	true	返回 JSON 响应，而不是 SSE 流
PROXMOX_MCP_ALLOWED_HOSTS	—	接受的 Host 标头；* 表示禁用检查
PROXMOX_MCP_ALLOWED_ORIGINS	—	允许的浏览器来源；留空 = 仅允许同源

前缀是 PROXMOX_MCP_，而不是 PROXMOX_，因为 Kubernetes 会为每个关联的 Service 注入 <SERVICE>_PORT——否则名为 proxmox 的 Service 会重新定义 PROXMOX_PORT。

不使用会话（stateless_http）：协议在修订版 2026-07-28 中移除了会话，因此多个客户端可以共用一个 URL，滚动更新也不会中断任何客户端。

Host 和 Origin 验证。 绑定到回环地址以外的地址时，必须设置 PROXMOX_MCP_ALLOWED_HOSTS；否则服务器会拒绝启动。来自外部的 Origin 会收到 403，意外的 Host 会收到 421——这可以防止同一局域网上浏览器中的页面通过 DNS 重绑定驱动服务器。没有 Origin 标头的请求（curl、MCP 客户端）始终通过验证。只有当前置组件已进行验证时，才设置 PROXMOX_MCP_ALLOWED_HOSTS=*。

此服务没有身份验证。 任何能够访问端点的人都可以使用 PROXMOX_RISK_LEVEL 所允许的功能。请将其置于网关、身份验证代理或可信的网络边界之后；除非访问路径经过身份验证，否则请保持 PROXMOX_RISK_LEVEL=read。

健康检查端点 与 /mcp 一同提供，且无需身份验证：

路径	含义
GET /healthz	进程正在运行。不会访问 Proxmox——如果 Proxmox 宕机就导致存活探针失败，服务器会陷入重启循环，且无法解决任何问题。
GET /readyz	Proxmox 已响应 version.get()。此端点应用于控制流量；否则返回 503 和易于理解的原因。

livenessProbe:
  httpGet: { path: /healthz, port: 8000 }
readinessProbe:
  httpGet: { path: /readyz, port: 8000 }

这些标志与变量对应，可用于交互式操作：uvx proxmox-ve-mcp --transport streamable-http --port 8080。

Sentry（可选）

可以将工具调用和失败事件发送到 Sentry——每个 tools/call 都会成为一个 span，每个失败的工具都会生成一个 issue。未设置 SENTRY_DSN 时，不会发送任何内容，甚至不会导入 SDK。

ghcr.io 镜像已包含 SDK。通过 PyPI 安装时，请安装附加依赖：

uvx --from 'proxmox-ve-mcp[sentry]' proxmox-ve-mcp

变量	默认值	描述
SENTRY_DSN	—	设置后启用报告
SENTRY_ENVIRONMENT	production	自定义环境标签
SENTRY_TRACES_SAMPLE_RATE	1.0	跟踪的工具调用比例
SENTRY_SEND_DEFAULT_PII	false	将工具参数和结果作为 span 数据发送

除非确定需要，否则请勿启用 SENTRY_SEND_DEFAULT_PII：启用后，工具参数和结果会附加到 span 中，而 get_vm_config 会返回 ssh 密钥和 cipassword 哈希值。如果设置了 DSN，但未安装附加依赖，则会记录警告，服务器仍会继续运行。

工具

节点（10）

工具	描述
list_nodes	列出所有集群节点及其状态、CPU、内存和运行时间
get_node_status	节点详细指标（CPU、内存、磁盘、负载、内核）
get_node_networks	节点上的网络接口
get_node_disks	节点上的物理磁盘
get_node_services	Proxmox 系统服务及其状态
get_node_updates	待处理的 APT 软件包更新
get_node_rrd_data	历史 CPU/内存/磁盘/网络指标（RRD）
get_node_tasks	节点上的近期任务，可选择仅显示错误
get_task_status	根据 UPID 查询特定任务的状态
get_task_log	任务的日志输出

QEMU 虚拟机（17）

工具	层级	描述
list_vms	read	列出所有虚拟机，可按节点筛选
get_vm_status	read	当前虚拟机状态（运行/停止、CPU、内存）
get_vm_config	read	虚拟机配置（硬件、磁盘、网络）
get_vm_network_interfaces	read	正在运行的虚拟机的IP 地址（通过 QEMU 客户机 Agent）
get_vm_rrd_data	read	历史 CPU/内存/磁盘/网络指标（RRD）
list_vm_snapshots	read	列出虚拟机的所有快照
start_vm	lifecycle	启动虚拟机
stop_vm	lifecycle	强制停止虚拟机——标记为破坏性操作，未保存的客户机状态将丢失
shutdown_vm	lifecycle	使用超时设置执行 ACPI 正常关机
reboot_vm	lifecycle	通过 ACPI 重启
suspend_vm	lifecycle	挂起虚拟机
resume_vm	lifecycle	恢复已挂起的虚拟机
clone_vm	lifecycle	完整克隆或链接克隆
migrate_vm	lifecycle	将虚拟机迁移到另一节点，可在线或离线迁移
create_vm_snapshot	lifecycle	创建快照
delete_vm_snapshot	all	删除快照
rollback_vm_snapshot	all	回滚到快照

LXC 容器（13）

工具	层级	描述
list_containers	read	列出所有 LXC 容器，可按节点筛选
get_container_status	read	当前容器状态
get_container_config	read	容器配置
get_container_interfaces	read	正在运行的容器的IP 地址
get_container_rrd_data	read	历史 CPU/内存/磁盘/网络指标（RRD）
list_container_snapshots	read	列出所有快照
start_container	lifecycle	启动容器
stop_container	lifecycle	强制停止容器——标记为破坏性操作
shutdown_container	lifecycle	使用超时设置正常关机
reboot_container	lifecycle	重启容器
create_container_snapshot	lifecycle	创建快照
delete_container_snapshot	all	删除快照
rollback_container_snapshot	all	回滚到快照

存储（2）

工具	描述
list_storage	列出存储池及其用量，可按节点筛选
get_storage_content	存储池的内容（ISO、备份、镜像、模板）

集群（7）

工具	描述
get_cluster_status	集群健康状况、仲裁状态和节点成员信息
get_cluster_resources	所有资源（虚拟机、容器、存储、节点）
get_cluster_backups	已配置的备份作业
get_ha_status	高可用资源及其状态
list_pools	资源池
get_cluster_log	集群范围的事件日志，按时间从新到旧排列
get_next_vmid	下一个可用的虚拟机/容器 ID

服务器（1）

工具	描述
get_server_info	此服务器自身的风险级别、工具数量、版本和 Proxmox 可访问性

架构

src/proxmox_mcp/
├── server.py    # MCPServer instance, health routes, transport selection, entry point
├── config.py    # Pydantic Settings (PROXMOX_) + transport config (PROXMOX_MCP_)
├── client.py    # Proxmoxer connection, built once per process
└── tools/       # nodes, vms, containers, storage, cluster, server_info

• 默认只读 — 高权限工具由 PROXMOX_RISK_LEVEL 控制
• 在注册时进行门控 — 高于指定级别的工具不会出现在 tools/list 中，而不是在调用时被拒绝：模型看不到的内容，就无法重试
• 准入与注释相互独立 — tier= 是操作员的策略，annotations= 是告知客户端调用会执行什么操作，因此强制停止可以设置为 destructiveHint: true，同时仍属于 lifecycle 级别
• 延迟连接 — Proxmoxer 客户端仅在首次使用时创建一次，并由所有调用共享；因此，即使无法访问 Proxmox，服务也能正常启动
• 原始 JSON 输出 — 紧凑且不做格式化；大模型可直接使用数据
• 标准化错误 — Proxmox 和网络故障会转换为一句可采取行动的说明，而不是 requests 回溯信息

开发

独立运行（测试）

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

docker run -i --rm \
  -e PROXMOX_HOST -e PROXMOX_USER \
  -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  ghcr.io/akmalovaa/proxmox-mcp:latest

不使用 Docker（UV）

git clone https://github.com/akmalovaa/proxmox-mcp.git && cd proxmox-mcp && uv sync

MCP 客户端配置：

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "python", "-m", "proxmox_mcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

从源代码构建

git clone https://github.com/akmalovaa/proxmox-mcp.git
cd proxmox-mcp
docker build -t proxmox-mcp .

该镜像采用多阶段构建：uv 在临时层中构建虚拟环境，运行时阶段仅包含 Python 和虚拟环境，并以非特权 mcp 用户（uid 10001）运行。

代码检查、类型检查、测试

uv sync --locked --group dev
uv run ruff check .
uv run mypy src/
uv run pytest -v

许可证

MIT