AI导哈

Proxmox VE动态API服务器

一个基于OpenAPI的Proxmox VE动态API服务器，通过2个通用工具执行480+API操作，显著减少95%的令牌消耗。

  • by bakhshb
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 bakhshb/proxmox-mcp-openapi

使用说明

@bakhshb/proxmox-mcp-openapi

开源

一 OpenAPI驱动的双工具MCP服务器 对于Proxmox VE。它没有定义35+显式工具，而是只公开了2个通用工具，可以动态执行480+Proxmox API操作中的任何一个，以及用于在虚拟机和容器内执行命令的专用工具。

节省约95%的代币 与传统的显式工具MCP服务器相比。

工具

proxmox-api

动态执行任何Proxmox VE API操作。

参数 类型 必填 描述
path string yes neneneba API路径，例如。 /nodes/{node}/qemu/{vmid}/status/current
method enum no HTTP方法（如果省略，则自动检测）
pathParams object no 路径参数值，例如。 {"node": "pve", "vmid": 100}
params object no 查询参数（GET）或请求体（POST/PUT/PATCH）

proxmox-api-schema

从OpenAPI规范中查找可用的API操作。

参数 类型 必填 描述
tag string no 按标签筛选： nodes, cluster, storage, access, pools
path string no 获取特定路径的详细信息
method enum no 按HTTP方法筛选

proxmox-execute-container-command

通过SSH在LXC容器内执行shell命令+ pct exec.

注： Proxmox REST API没有用于LXC命令执行的端点。此工具SSHe连接到Proxmox节点并运行 pct exec 当地。

参数 类型 必填 描述
node string yes Proxmox节点名称（例如。 pve)
vmid string number yes
command string yes 在容器内运行的Shell命令

退货： { success, exitCode, output, error, node, vmid, command }

proxmox-execute-vm-command

通过QEMU来宾代理在VM内执行命令。

要求： VM必须与一起运行 qemu-guest-agent 安装在客人体内。

参数 类型 必填 描述
node string no Proxmox节点名称（默认值： pve)
vmid number yes VM ID（例如。 100)
command string yes 带参数的单个可执行文件（无管道/重定向）
timeoutMs number no 超时（毫秒）（默认值： 30000)

退货： { success, exitCode, output, error, outTruncated?, errTruncated? }

安装

先决条件

  • Node.js 18+
  • npm 或 纱线
  • 带有API令牌的Proxmox VE实例
  • 对于容器命令：SSH密钥访问Proxmox节点

选项1：克隆和构建

# Clone the repository
git clone https://github.com/bakhshb/proxmox-mcp-openapi.git
cd proxmox-mcp-openapi

# Install dependencies
npm install

# Build TypeScript
npm run build

选项2:npm包

npm install -g @bakhshb/proxmox-mcp-openapi

然后向您的MCP客户端注册（请参阅 MCP客户端配置).

配置

环境变量

cp .env.example .env

必修的：

变量 描述
PROXMOX_URL 基本URL包括 /api2/json例如。 https://pve.example.com:8006/api2/json
PROXMOX_API_TOKEN 令牌在 user@realm!tokenid=secret 格式

可选：

变量 默认值 描述
PROXMOX_INSECURE false 跳过TLS证书验证（对于自签名证书）
PROXMOX_TIMEOUT 30000 请求超时（毫秒）
PROXMOX_SSH_KEY_PATH ~/.ssh/proxmox_mcp SSH私钥的路径
PROXMOX_SSH_USER root SSH用户名
PROXMOX_SSH_PORT 22 SSH端口

Proxmox API令牌设置

  1. 在Proxmox Web用户界面中： 数据中心→ 权限→ API令牌→ Add
  2. 按以下格式复制令牌： user@realm!tokenid=secret
  3. 为令牌分配适当的权限（例如，PVEAuditor用于只读，PVEEditor用于修改）

SSH密钥设置（用于容器命令）

# Generate SSH key
ssh-keygen -t ed25519 -f ~/.ssh/proxmox_mcp

# Add public key to Proxmox
# Copy: cat ~/.ssh/proxmox_mcp.pub
# Paste in: Proxmox Web UI → Permissions → SSH Keys → Add

MCP客户端配置

开爪

{
  "mcp": {
    "servers": {
      "proxmox-mcp": {
        "command": "npx",
        "args": ["@bakhshb/proxmox-mcp-openapi"],
        "env": {
          "PROXMOX_URL": "https://your-proxmox:8006/api2/json",
          "PROXMOX_API_TOKEN": "root@pam!mytoken=your-secret",
          "PROXMOX_INSECURE": "true",
          "PROXMOX_SSH_KEY_PATH": "~/.ssh/proxmox_mcp"
        }
      }
    }
  }
}

克劳德桌面

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "npx",
      "args": ["@bakhshb/proxmox-mcp-openapi"],
      "env": {
        "PROXMOX_URL": "https://your-proxmox:8006/api2/json",
        "PROXMOX_API_TOKEN": "root@pam!mytoken=your-secret",
        "PROXMOX_INSECURE": "true",
        "PROXMOX_SSH_KEY_PATH": "~/.ssh/proxmox_mcp"
      }
    }
  }
}

VS代码副本

将相同的配置添加到 settings.json 在...之下 mcp.servers.

用法示例

API操作

// Get VM status
proxmox-api path="/nodes/pve/qemu/100/status/current"

// List all VMs
proxmox-api path="/nodes/pve/qemu"

// Start a VM
proxmox-api path="/nodes/pve/qemu/100/status/start" method=POST

// Get cluster resources
proxmox-api path="/cluster/resources"

// Discover storage operations
proxmox-api-schema tag="storage"

// Get parameters for a specific endpoint
proxmox-api-schema path="/nodes/{node}/qemu/{vmid}/config"

容器命令

// Get OS version
proxmox-execute-container-command node="pve" vmid=110 command="cat /etc/os-release"

// Check hostname
proxmox-execute-container-command node="pve" vmid=110 command="hostname"

// Disk usage
proxmox-execute-container-command node="pve" vmid=110 command="df -h"

// Update packages
proxmox-execute-container-command node="pve" vmid=110 command="apt update && apt upgrade -y"

VM命令

// Simple command
proxmox-execute-vm-command node="pve" vmid=100 command="hostname"
// → { success: true, output: "dokploy-swarm-1" }

// Check disk space (note: no flags, QEMU agent limitation)
proxmox-execute-vm-command node="pve" vmid=100 command="df"
// → { success: true, output: "Filesystem..." }

// For shell features (pipes, redirects), use proxmox-api directly:
// 1. POST /agent/exec with input-data for stdin
// 2. GET /agent/exec-status?pid=<pid>

代币节省

与传统MCP架构的比较

MCP服务器 架构 工具 令牌成本
传统Proxmox MCP 每个API操作一个工具 约35个显式工具 约15000–20000个代币
@bakhshb/proxmox-mcp-openapi OpenAPI驱动的动态 2个通用工具+2个执行工具 ~500–1000个令牌

结果：约95%的代币减少

为什么代币很重要

MCP服务器在每次请求时都会将其工具模式发送给LLM。使用200k令牌上下文窗口：

  • 传统方法：15-20k令牌仅用于模式，实际工作空间较小
  • OpenAPI驱动：约500个令牌，为您的数据留下上下文窗口

运作原理

不要硬编码所有工具：

// Traditional: 35+ explicit tools
server.tool("list_nodes", {...})
server.tool("get_vm_status", {...})
server.tool("start_vm", {...})
// ... 30 more

// OpenAPI-driven: 2 dynamic tools
server.tool("proxmox-api", {...})           // executes any API operation
server.tool("proxmox-api-schema", {...})    // discovers available operations

模式在启动时从OpenAPI规范加载，而不是在工具中硬编码。

灵感

该项目基于两个关键灵感：

  1. ProxmoxMCP Plus -用于Proxmox VE的原始35工具Python MCP服务器。它证明了整个API表面积，但具有较高的令牌开销。

  2. 利姆霍克/dokploy mcp -证明了2工具OpenAPI驱动模式可以显著降低代币成本，同时保持API的全面覆盖。

proxmox-mcp-openapi综合了两者的优点：dokploy-mcp应用于proxmox的动态openapi方法，以及ProxmoxMCP-Plus继承的其他基于SSH的容器命令执行工具。

架构模式

Traditional MCP:   35 tools × detailed schemas = 15k+ tokens
                   ↓
OpenAPI-driven:    2 tools + runtime schema loading = ~500 tokens
                   ↓
Result:           95% token reduction with full API coverage

建筑

  • 2个核心工具 + 2个执行工具
  • OpenAPI驱动：从规范中动态加载480个操作
  • TypeScript：类型安全，编译为JavaScript
  • 纯REST API：没有Proxmox Perl库依赖项
  • SSH密钥认证 对于容器命令（LXC执行不需要API令牌）
  • 遗留的执行工具 从最初的ProxmoxMCP Plus（LXC的SSH+pct，VM的QEMU代理）

OpenAPI规范

包括Proxmox VE API v2规范，共有480个操作：

  • cluster （122次操作）
  • nodes （311次操作）
  • storage （5次操作）
  • access （36次操作）
  • pools （5次操作）
  • version （1次操作）

故障排除

容器命令上的“拒绝访问”

  1. 验证添加到Proxmox Web UI的SSH密钥→ 权限→ SSH 密钥
  2. 验证容器是否 跑步 （未停止）
  3. 手动测试SSH： ssh -i ~/.ssh/proxmox_mcp root@<proxmox-host>

“SSH连接超时”

  1. 检查 node 参数正确（使用节点名称，如 pve，不是IP）
  2. 验证SSH是否在Proxmox节点上运行
  3. 检查防火墙是否允许端口22

API返回401/403

  1. 验证令牌格式： user@realm!tokenid=secret （不仅仅是UUID）
  2. 检查令牌在Proxmox中是否具有适当的权限

VM命令失败，出现596

  • QEMU代理不支持shell功能（管道、重定向）
  • 使用 proxmox-api 直接与 input-data 对于stdin

VM命令失败，出现404

  • QEMU来宾代理未安装或未在VM内运行
  • 安装方式： apt install qemu-guest-agent （Linux）或通过Hyper-V/VMware工具启用

许可证

麻省理工学院

相关 MCP