MCP PVE

MCP-PVE

MCP服务器 Proxmox VE.通过Cursor、Claude Code和Claude Desktop中的自然语言管理虚拟机、容器、存储、网络和集群。

特性

• 105工具 穿过 12个类别 覆盖Proxmox VE REST API
• 三个访问层 (read-only, read-execute, full)用于粒度控制
• 类别筛选 通过 PVE_CATEGORIES 仅公开您需要的工具
• 零HTTP依赖 --使用本地 fetch （节点18+）
• 自签名证书支持 通过 PVE_VERIFY_SSL=false
• Docker镜像 为了 linux/amd64 和 linux/arm64 上 GHCR
• 远程MCP 通过HTTP传输(MCP_TRANSPORT=http)使用流式HTTP协议
• Types/ESM 具有全类型安全性

API兼容性

使用Proxmox VE进行测试 9.0.10.

快速开始

使用npx直接运行服务器：

PVE_BASE_URL="https://pve.example.com:8006" \
PVE_TOKEN_ID="root@pam!mcp" \
PVE_TOKEN_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
npx -y @samik081/mcp-pve

服务器在启动时验证您的PVE连接，如果凭据丢失或无效，则立即失败并显示明确的错误。

码头工人

使用Docker运行（stdio传输，与npx相同）：

docker run --rm -i \
  -e PVE_BASE_URL=https://pve.example.com:8006 \
  -e PVE_TOKEN_ID=root@pam!mcp \
  -e PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e PVE_VERIFY_SSL=false \
  ghcr.io/samik081/mcp-pve

要作为具有HTTP传输的远程MCP服务器运行：

docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e PVE_BASE_URL=https://pve.example.com:8006 \
  -e PVE_TOKEN_ID=root@pam!mcp \
  -e PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e PVE_VERIFY_SSL=false \
  ghcr.io/samik081/mcp-pve

MCP端点位于 http://localhost:3000 健康检查在 http://localhost:3000/health.

配置

Claude Code命令行界面（推荐）：

# Using npx
claude mcp add --transport stdio pve \
  --env PVE_BASE_URL=https://pve.example.com:8006 \
  --env PVE_TOKEN_ID=root@pam!mcp \
  --env PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --env PVE_VERIFY_SSL=false \
  -- npx -y @samik081/mcp-pve

# Using Docker
claude mcp add --transport stdio pve \
  --env PVE_BASE_URL=https://pve.example.com:8006 \
  --env PVE_TOKEN_ID=root@pam!mcp \
  --env PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --env PVE_VERIFY_SSL=false \
  -- docker run --rm -i ghcr.io/samik081/mcp-pve

# Using remote HTTP (connect to a running Docker container or HTTP server)
claude mcp add --transport http pve http://localhost:3000

JSON配置 （与Claude Code合作 .mcp.json，克劳德桌面 claude_desktop_config.json，光标 .cursor/mcp.json):

{
  "mcpServers": {
    "pve": {
      "command": "npx",
      "args": ["-y", "@samik081/mcp-pve"],
      "env": {
        "PVE_BASE_URL": "https://pve.example.com:8006",
        "PVE_TOKEN_ID": "root@pam!mcp",
        "PVE_TOKEN_SECRET": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "PVE_VERIFY_SSL": "false"
      }
    }
  }
}

Docker（标准操作系统）：

{
  "mcpServers": {
    "pve": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "PVE_BASE_URL=https://pve.example.com:8006",
        "-e", "PVE_TOKEN_ID=root@pam!mcp",
        "-e", "PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "-e", "PVE_VERIFY_SSL=false",
        "ghcr.io/samik081/mcp-pve"
      ]
    }
  }
}

远程MCP （连接到正在运行的Docker容器或HTTP服务器）：

{
  "mcpServers": {
    "pve": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}

访问层

使用控制哪些工具可用 PVE_ACCESS_TIER 环境变量：

层级详细信息：

• 满的：全部105个工具。包括创建/删除虚拟机、容器、存储、用户、防火墙规则等。
• 读取执行：68个工具。所有读取工具以及电源操作（启动、停止、迁移）、备份执行和任务管理。
• 只读：51个工具。仅列出、获取、状态和日志工具。没有状态变化。

您层中不可用的工具未在MCP服务器上注册。它们不会出现在你的人工智能工具的工具列表中，保持上下文干净。

环境变量

在下的PVE UI中创建API内标识 数据中心>权限>API令牌。如果您希望令牌继承用户的完全权限，请确保取消选中“特权分离”。

可用类别

nodes, qemu, lxc, storage, cluster, access, pools, network, firewall, backup, tasks, ha

工具

mcp-pve提供了105个按类别组织的工具。每个工具的“访问”列显示了所需的最低级别： read-only （适用于所有级别）， read-execute （要求 read-execute 或 full)，或 full （要求 full 仅限级别）。提示列显示工具行为： read-only （无状态变化）， destructive （修改现有状态）， idempotent （如果调用两次，结果相同）。

Nodes (8 tools)

QEMU Virtual Machines (20 tools)

LXC Containers (18 tools)

Storage (8 tools)

Cluster (9 tools)

Access Control (10 tools)

Pools (5 tools)

Network (5 tools)

Firewall (8 tools)

Backup (5 tools)

Tasks (4 tools)

High Availability (5 tools)

验证它是否有效

配置完MCP客户端后，询问您的AI助手：

“我的Proxmox群集中有哪些节点？”

如果连接正常，助理会打电话 pve_list_nodes 并返回节点的当前状态。

用法示例

配置后，用自然语言向您的AI工具提问：

• “列出节点pve1上的所有虚拟机” --电话 pve_list_qemu_vms 显示VM的状态、CPU和内存使用情况。

• “VM 100的状态如何？” --电话 pve_get_qemu_status 以显示实时资源利用率。

• “在pve1上启动容器200” --电话 pve_start_lxc_container 启动容器并返回任务UPID。

• “创建VM 100的快照，称为预升级” --电话 pve_create_qemu_snapshot 在更改之前创建快照。

• “显示群集资源” --电话 pve_list_cluster_resources 显示所有VM、容器、存储和节点。

• “将VM 100迁移到节点pve2” --电话 pve_migrate_qemu_vm 将VM实时迁移到另一个节点。

故障排除

连接被拒绝/ECONNREFUSED

检查一下 PVE_BASE_URL 正确且包含端口（默认值：8006）。确保可以从运行MCP服务器的位置访问PVE主机。

SSL证书错误

如果您的PVE实例使用自签名证书，请设置 PVE_VERIFY_SSL=false。这将禁用所有请求的TLS验证。

工具未显示

检查您的访问层设置。在 read-only 模式下，仅注册了51个工具。在 read-execute 模式下，注册了68个工具。使用 full （或省略 PVE_ACCESS_TIER)所有105个工具。检查 PVE_CATEGORIES --仅注册所列类别中的工具。还可以通过检查stderr输出来验证服务器是否已正确启动。

发展

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (auto-reload)
npm run dev

# Open the MCP Inspector for interactive testing
npm run inspect

许可证

麻省理工学院