Proxmox MCP is an opinionated MCP server

Proxmox MCP 服务

NOTE: 此项目正在积极开发中。

动机

现代基础设施通常会使用 Terraform/OpenTofu、Ansible 和 GitOps 等工具。这些工具用于部署和配置 Proxmox 基础设施 以及 Kubernetes 集群。

Proxmox MCP 服务不会取代这些工具，而是让 AI 助手 和自动化 Agent 能够访问 Proxmox 集群的信息。

默认工具为只读工具。对于备份和重启等操作，可以通过 --allow-destructive 启用可选的操作工具。

你无需在 Proxmox UI 中查看许多页面，也无需运行多条命令， 只需让 AI 助手收集并分析所需信息即可。 现有的自动化工具仍是基础设施变更的主要方式。

概览

此服务将 MCP 客户端（例如 AI 助手）连接到 Proxmox VE API。 它支持多个 Proxmox 集群，并返回结构化数据。

你可以使用它来：

• 检查集群、节点和存储
• 查看资源使用情况和节点状态
• 查看最近的 Proxmox 任务事件
• 查找差异和可能的配置问题
• 在进行基础设施变更前收集信息

给你的 AI 拴好缰绳。

Proxmox 核心工具

MCP 服务提供以下只读工具：

工具	参数	描述
proxmox_clusters_list	无	列出已配置的 Proxmox 集群。
proxmox_clusters_describe	cluster	显示集群的版本、节点、节点状态和总资源。
proxmox_containers_list	cluster	列出 LXC 容器及其状态和资源使用情况。
proxmox_containers_describe	cluster、vmid、node（可选）	显示 LXC 容器的当前状态；如果容器正在运行，还会显示其运行时网络接口。
proxmox_events_list	cluster、limit（可选）	列出所有节点上的近期任务事件。默认限制为 10。
proxmox_nodes_list	cluster	列出节点及其状态和资源使用情况。
proxmox_nodes_describe	cluster、node	显示节点的状态、资源、运行时间、版本、内核和启动信息。
proxmox_storage_list	cluster	列出存储资源及其状态、类型、内容和容量使用情况。
proxmox_storage_describe	cluster、name、node（可选）	显示存储详情；如果提供了节点，还会显示该节点可见的内容。
proxmox_vms_list	cluster	列出 QEMU 虚拟机及其状态和资源使用情况。
proxmox_vms_describe	cluster、vmid、node（可选）	显示 QEMU 虚拟机的当前状态；当其 QEMU Guest Agent 正常响应时，还会显示客户机网络接口。

首先使用 proxmox_clusters_list 查找其他工具所需的集群名称。MCP 客户端可以发现完整的输入和输出架构。你也可以通过命令行列出工具：

proxmox-mcp tools --config /absolute/path/to/cluster-config.yaml

启用 --allow-destructive 后，proxmox_vms_backup 和 proxmox_containers_backup 接受 cluster、vmid、可选的 node、 storage、mode 和 compress 参数。它们会启动异步备份 并返回 Proxmox 任务标识符；创建任务并不意味着备份已经成功完成。

安装

如需使用 Homebrew 进行本地安装，请运行：

brew install sergelogvinov/tap/proxmox-mcp

如果你使用的是托管在其他机器上的 MCP 服务，则无需本地安装。

配置 Proxmox 集群

创建一个 YAML 文件，其中包含一个或多个 Proxmox 集群：

clusters:
  - region: homelab
    url: https://pve.example.com:8006/api2/json
    token_id: mcp@pve!reader
    token_secret_file: /absolute/path/to/token-secret
    ca_file: /absolute/path/to/proxmox-ca.crt

每个集群支持以下字段：

字段	必填	说明
region	是	唯一名称，用于在工具调用中选择集群。
url	是	完整的 Proxmox API URL，包括 /api2/json。
token_id	使用令牌登录时	Proxmox API 令牌 ID，例如 mcp@pve!reader。
token_id_file	使用令牌登录时	包含令牌 ID 的文件。使用此字段代替 token_id。
token_secret	使用令牌登录时	Proxmox API 令牌密钥。
token_secret_file	使用令牌登录时	包含令牌密钥的文件。使用此字段代替 token_secret。
username	使用密码登录时	Proxmox 用户名。必须与 password 一起使用。
password	使用密码登录时	Proxmox 密码。必须与 username 一起使用。
ca_file	否	用于验证 Proxmox TLS 证书的 CA 证书路径。
insecure	否	跳过 TLS 证书检查。仅用于本地测试。默认值：false。

每个集群只能使用令牌登录或密码登录，不能同时使用两种方式。建议将密钥 存储在文件中，以免将密钥值写入 YAML 文件。 Proxmox 账户应仅具有工具所需的权限。

使用 --config 或 CONFIG_FILE 设置配置文件路径。

配置 MCP 客户端

本地 stdio 服务

对于使用 JSON MCP 配置的客户端，请添加如下条目：

{
  "mcpServers": {
    "proxmox": {
      "command": "proxmox-mcp",
      "args": ["mcp"],
      "env": {
        "CONFIG_FILE": "/absolute/path/to/cluster-config.yaml"
      }
    }
  }
}

远程 HTTP 服务

使用以下命令启动可流式传输的 HTTP 服务：

proxmox-mcp server \
  --config /absolute/path/to/cluster-config.yaml \
  --listen-address :8080

:8080 会接受来自所有 IPv4 和 IPv6 地址的连接。若要仅监听一个 地址，请将地址与端口一起指定，例如 127.0.0.1:8080 或 [::1]:8080。 MCP 端点为 http://host:8080/mcp

对于远程客户端，请使用以 /mcp 结尾的 HTTPS URL：

{
  "mcpServers": {
    "proxmox": {
      "type": "http",
      "url": "https://proxmox-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer PVEAPIToken=mcp@pve!reader=TOKEN_SECRET"
      }
    }
  }
}

该服务不会为 HTTP 端点提供用户身份验证。 它依靠 Proxmox 身份验证和 API 令牌进行访问控制。 像这样在 MCP 标头中提供令牌：

Authorization: PVEAPIToken=mcp@pve!reader=TOKEN_SECRET

存在此标头时，工具调用将使用其中的令牌，而不是集群配置中的 凭据。配置的集群仍必须包含 region 和 url。

保存配置后，重启或重新加载 MCP 客户端。

运行

常用标志

mcp、server 和 tools 命令使用以下标志。每个标志 也可以通过环境变量设置。命令行标志的优先级高于环境变量。

标志	环境变量	默认值	说明
--config <path>	CONFIG_FILE	无	必需的集群 YAML 配置文件路径。
--extensions <list>	EXTENSIONS	all	要启用的扩展列表，以逗号分隔；也可以使用 all。
--allow-destructive	ALLOW_DESTRUCTIVE	false	在可用时允许使用有破坏性的工具。目前的核心工具为只读工具。
--log-level <level>	LOG_LEVEL	info	日志级别：debug、info、warn 或 error。
--log-format <format>	LOG_FORMAT	text	日志输出格式：text 或 json。

server 命令还接受 --listen-address 或 LISTEN_ADDRESS （host:port）。默认值为 127.0.0.1:8080，容器镜像设置的 LISTEN_ADDRESS=:8080。tools 命令接受 --output（-o），可选值为 text、json 或 yaml。其默认值为 text。

例如，使用 JSON 日志运行 stdio 服务：

proxmox-mcp mcp \
  --config /absolute/path/to/cluster-config.yaml \
  --log-format json

测试配置

列出所有可用工具：

export CONFIG_FILE="/absolute/path/to/cluster-config.yaml"
proxmox-mcp tools

直接调用工具：

proxmox-mcp tools proxmox_clusters_list
proxmox-mcp tools proxmox_nodes_list cluster=homelab
proxmox-mcp tools -o json proxmox_events_list cluster=homelab limit=5

许可证

本软件根据 Apache License, Version 2.0（以下简称“许可证”）授权； 除非遵守许可证，否则不得使用此文件。 你可以通过以下地址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或经书面同意，否则根据许可证分发的软件 均按“原样”提供，不附带任何明示或暗示的保证或条件。 有关许可证规定的权限和限制，请参阅许可证。

---

Proxmox® 是 Proxmox Server Solutions GmbH 的注册商标。