Skip to main content
Glama
proxmox-mcp

proxmox-mcp

proxmox-mcp

一个专为 Proxmox VE 设计的 Docker 优先模型上下文协议 (MCP) 服务器。

它提供了安全、结构化的工具,用于只读集群检查、虚拟机/容器生命周期操作、快照、迁移、配置辅助,以及一个带有防护的通用 Proxmox API 逃生舱。

状态

Alpha 版本。采用 API 令牌认证,并为变更性操作设置了明确的确认门控。

Related MCP server: Proxmox MCP Server

使用 Docker Compose 运行

Docker Compose 是运行此 MCP 服务器的主要支持方式。

cp .env.example .env
# edit .env with your Proxmox URL and token
docker compose up -d --build

默认情况下,MCP 服务器监听:

http://127.0.0.1:8000/mcp

.env.example 中的默认 MCP 传输设置:

MCP_TRANSPORT=streamable-http
MCP_PORT=8000
MCP_PATH=/mcp

在 Docker 内部,应用程序绑定到容器内的 0.0.0.0,但 Compose 默认仅将其发布在主机回环地址上:

ports:
  - "127.0.0.1:8000:8000"

除非你在其前方部署了实际的网络控制措施,否则请勿在所有接口上发布此未经身份验证的 MCP 端点。

支持的 MCP 传输方式:

  • streamable-http — Docker 和大多数远程部署的默认方式

  • sse — 旧版 HTTP/SSE MCP 传输

  • stdio — 本地子进程模式

如需通过 HTTPS 公开 MCP 端点,请将此服务置于反向代理(如 Caddy、Traefik 或 nginx)之后,并在该处终止 TLS。除非有特殊原因,否则请在内部保持容器使用纯 HTTP。

Proxmox 协议配置

建议 Proxmox API 使用 HTTPS:

PVE_BASE_URL=https://proxmox.lan:8006
PVE_VERIFY_SSL=false # only for self-signed homelab certs

如果你确实需要为 Proxmox 使用纯 HTTP,请明确指定:

PVE_BASE_URL=http://proxmox.lan:8006
PVE_ALLOW_INSECURE_HTTP=true

纯 HTTP 会在网络上传输凭据。在严格控制的实验室网络之外,这通常不是一个好主意。

身份验证

建议使用 Proxmox API 令牌:

PVE_API_TOKEN_ID=user@pam!token-name
PVE_API_TOKEN_SECRET=replace-me

也支持密码票据认证,但 API 令牌对于 MCP 来说更简洁:

PVE_USERNAME=user@pam
PVE_PASSWORD=replace-me

用于 Docker HTTP MCP 的 Hermes 配置

mcp_servers:
  proxmox:
    url: "http://127.0.0.1:8000/mcp"
    timeout: 120
    connect_timeout: 30

如果部署在 TLS 后方的远程主机上:

mcp_servers:
  proxmox:
    url: "https://proxmox-mcp.example.internal/mcp"
    timeout: 120
    connect_timeout: 30

不使用 Docker 运行

本地 stdio 模式仍可用于开发:

MCP_TRANSPORT=stdio uvx proxmox-mcp
# or from a checkout:
MCP_TRANSPORT=stdio uv run proxmox-mcp

不使用 Docker 的本地 HTTP 模式:

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run proxmox-mcp

安全模型

  • 默认允许 GET 请求。

  • POST、PUT 和 DELETE 请求需要 confirm=true。

  • 高级生命周期/配置工具也需要 confirm=true。

  • 绝不会有意返回机密信息。

  • 通用 API 路径会拒绝完整的 URL、查询字符串、片段、路径遍历、编码后的路径遍历以及编码后的斜杠技巧。

  • 路径段在发送到 Proxmox 之前会经过验证和编码。

工具覆盖范围

第一阶段:只读

  • pve_get_version

  • pve_get_cluster_status

  • pve_list_nodes

  • pve_list_resources

  • pve_list_vms

  • pve_get_vm_status

  • pve_get_vm_config

  • pve_list_storage

  • pve_list_backups

  • pve_get_task_status

  • pve_get_node_metrics

第二阶段:安全操作

  • pve_start_vm

  • pve_shutdown_vm

  • pve_stop_vm

  • pve_reboot_vm

  • pve_suspend_vm

  • pve_resume_vm

  • pve_create_snapshot

  • pve_delete_snapshot

  • pve_rollback_snapshot

  • pve_migrate_vm

第三阶段:管理/配置 + 逃生舱

  • pve_clone_vm

  • pve_create_lxc

  • pve_create_qemu_vm

  • pve_delete_vm

  • pve_resize_disk

  • pve_set_vm_config

  • pve_api_request

开发

uv sync --extra dev
uv run pytest
uv run ruff check .

Available Tools

28 tools
pve_api_requestC

Call any Proxmox API path. GET is allowed; POST/PUT/DELETE require confirm=true.

Inputs: path (required), method (required), params, confirm. Returns: object

pve_clone_vmC

Clone a QEMU VM. Requires confirm=true.

Inputs: node (required), newid (required), source_vmid (required), full, +4 more. Returns: object

pve_create_lxcC

Create an LXC container. Requires confirm=true.

Inputs: node (required), vmid (required), storage (required), ostemplate (required), +8 more. Returns: object

pve_create_qemu_vmC

Create a QEMU VM. Requires confirm=true.

Inputs: node (required), vmid (required), ide2, name, +7 more. Returns: object

pve_create_snapshotB

Create a VM/container snapshot. Requires confirm=true.

Inputs: node (required), vmid (required), snapname (required), confirm, +3 more. Returns: object

pve_delete_snapshotA

Delete a VM/container snapshot. Requires confirm=true.

Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object

pve_delete_vmC

Delete a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), purge, confirm, +2 more. Returns: object

pve_get_cluster_statusA

Return Proxmox cluster status.

Inputs: no named parameters. Returns: object

pve_get_node_metricsC

Get node status and metrics.

Inputs: node (required). Returns: object

pve_get_task_statusC

Get task status by UPID.

Inputs: node (required), upid (required). Returns: object

pve_get_versionA

Return Proxmox VE version information.

Inputs: no named parameters. Returns: object

pve_get_vm_configA

Get config for a QEMU VM or LXC container.

Inputs: node (required), vmid (required), vm_type. Returns: object

pve_get_vm_statusB

Get current status for a QEMU VM or LXC container.

Inputs: node (required), vmid (required), vm_type. Returns: object

pve_list_backupsB

List backup content for a node storage.

Inputs: node (required), storage (required). Returns: object

pve_list_nodesA

List Proxmox nodes.

Inputs: no named parameters. Returns: object

pve_list_resourcesB

List cluster resources, optionally filtered by type such as vm, storage, node.

Inputs: resource_type. Returns: object

pve_list_storageA

List storage globally or for a node.

Inputs: node. Returns: object

pve_list_vmsA

List QEMU VMs and LXC containers from cluster resources.

Inputs: no named parameters. Returns: object

pve_migrate_vmB

Migrate a VM/container to another node. Requires confirm=true.

Inputs: node (required), vmid (required), target (required), online, +4 more. Returns: object

pve_reboot_vmA

Reboot a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_resize_diskC

Resize a QEMU VM disk. Requires confirm=true.

Inputs: disk (required), node (required), size (required), vmid (required), +1 more. Returns: object

pve_resume_vmB

Resume a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_rollback_snapshotC

Rollback to a snapshot. Requires confirm=true.

Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object

pve_set_vm_configC

Update VM/container config. Requires confirm=true.

Inputs: node (required), vmid (required), config (required), confirm, +1 more. Returns: object

pve_shutdown_vmB

Gracefully shut down a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, timeout, +2 more. Returns: object

pve_start_vmC

Start a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_stop_vmA

Hard stop a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_suspend_vmC

Suspend a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools target a distinct resource/action combination, and lifecycle verbs like start, shutdown, stop, and reboot are clear. The main ambiguity comes from the overlapping read-only listing tools (list_resources, list_vms, list_nodes, list_storage), though the descriptions help differentiate them. pve_api_request is a deliberate escape hatch rather than a source of confusion.

    Naming Consistency5/5

    All tools follow a consistent pve_verb_noun snake_case pattern. Verbs are predictable: list/get for reads, create/delete/set for mutations, and explicit lifecycle verbs for VM/container actions. There are no mixed naming conventions or vague generic names.

    Tool Count2/5

    28 tools exceeds the 25+ threshold and feels heavy for a single server. Several listing and config tools could be consolidated, and the generic pve_api_request already provides broad fallback coverage. The domain is broad but the surface is larger than necessary.

    Completeness4/5

    Core VM/container lifecycle, snapshot management, migration, cloning, creation, deletion, config updates, and disk resize are covered. Notable gaps like LXC clone/resize and advanced storage/network management are not directly exposed, but pve_api_request provides a workaround. The surface has no critical dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An open-source MCP server for managing Proxmox environments, including nodes, virtual machines, and containers. It enables users to perform inventory checks, status monitoring, and control operations directly through MCP-compatible tools.
      109 npm
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      An MCP server that exposes Proxmox VE node/cluster as tools for MCP clients, enabling management of VMs and containers including power control, resource reconfiguration, snapshots, and backups.
      20
      MIT