Proxmox MCP Openapi

@bakhshb/proxmox-mcp-openapi

 开源

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

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

______________________________________________________________________

工具

proxmox-api

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

proxmox-api-schema

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

proxmox-execute-container-command

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

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

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

proxmox-execute-vm-command

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

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

退货： { 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 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=

______________________________________________________________________

代币节省

与传统MCP架构的比较

结果：约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表面积，但具有较高的令牌开销。

1. 利姆霍克/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@

`

“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工具启用

______________________________________________________________________

许可证

麻省理工学院