@bakhshb/proxmox-mcp-openapi

Open Source

An OpenAPI-driven 2-tool MCP server for Proxmox VE. Instead of defining 35+ explicit tools, it exposes just 2 generic tools that can execute any of the 480+ Proxmox API operations dynamically — plus dedicated tools for executing commands inside VMs and containers.

Saves ~95% tokens compared to traditional explicit-tool MCP servers.

Tools

proxmox-api

Execute any Proxmox VE API operation dynamically.

| Param | Type | Required | Description | |-------|------|----------|-------------| | path | string | yes | API path, e.g. /nodes/{node}/qemu/{vmid}/status/current | | method | enum | no | HTTP method (auto-detected if omitted) | | pathParams | object | no | Path parameter values, e.g. {"node": "pve", "vmid": 100} | | params | object | no | Query params (GET) or request body (POST/PUT/PATCH) |

proxmox-api-schema

Discover available API operations from the OpenAPI spec.

| Param | Type | Required | Description | |-------|------|----------|-------------| | tag | string | no | Filter by tag: nodes, cluster, storage, access, pools | | path | string | no | Get details for a specific path | | method | enum | no | Filter by HTTP method |

proxmox-execute-container-command

Execute shell commands inside LXC containers via SSH + pct exec.

Note: The Proxmox REST API has no endpoint for LXC command execution. This tool SSHes to the Proxmox node and runs pct exec locally.

| Param | Type | Required | Description | |-------|------|----------|-------------| | node | string | yes | Proxmox node name (e.g. pve) | | vmid | string|number | yes | Container ID (e.g. 110) | | command | string | yes | Shell command to run inside the container |

Returns: { success, exitCode, output, error, node, vmid, command }

proxmox-execute-vm-command

Execute commands inside VMs via QEMU guest agent.

Requirements: VM must be running with qemu-guest-agent installed inside the guest.

| Param | Type | Required | Description | |-------|------|----------|-------------| | node | string | no | Proxmox node name (default: pve) | | vmid | number | yes | VM ID (e.g. 100) | | command | string | yes | Single executable with args (no pipes/redirects) | | timeoutMs | number | no | Timeout in ms (default: 30000) |

Returns: { success, exitCode, output, error, outTruncated?, errTruncated? }

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• Proxmox VE instance with API token
• For container commands: SSH key access to Proxmox node

Option 1: Clone and Build

# 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

Option 2: npm Package

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

Then register with your MCP client (see MCP Client Configuration).

Configuration

Environment Variables

cp .env.example .env

Required: | Variable | Description | |----------|-------------| | PROXMOX_URL | Base URL including /api2/json, e.g. https://pve.example.com:8006/api2/json | | PROXMOX_API_TOKEN | Token in user@realm!tokenid=secret format |

Optional: | Variable | Default | Description | |----------|---------|-------------| | PROXMOX_INSECURE | false | Skip TLS cert verification (for self-signed certs) | | PROXMOX_TIMEOUT | 30000 | Request timeout in ms | | PROXMOX_SSH_KEY_PATH | ~/.ssh/proxmox_mcp | Path to SSH private key | | PROXMOX_SSH_USER | root | SSH username | | PROXMOX_SSH_PORT | 22 | SSH port |

Proxmox API Token Setup

1. In Proxmox Web UI: Datacenter → Permissions → API Tokens → Add
2. Copy the token in format: user@realm!tokenid=secret
3. Assign appropriate permissions to the token (e.g. PVEAuditor for read-only, PVEEditor for modifications)

SSH Key Setup (for Container Commands)

# 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 Client Configuration

OpenClaw

{
  "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"
        }
      }
    }
  }
}

Claude Desktop

{
  "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 Code Copilot

Add the same configuration to settings.json under mcp.servers.

Usage Examples

API Operations

// 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"

Container Commands

// 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 Commands

// 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>

Token Savings

Comparison with Traditional MCP Architecture

| MCP Server | Architecture | Tools | Token Cost | |------------|--------------|-------|------------| | Traditional Proxmox MCP | One tool per API operation | ~35 explicit tools | ~15,000–20,000 tokens | | @bakhshb/proxmox-mcp-openapi | OpenAPI-driven dynamic | 2 generic tools + 2 exec tools | ~500–1,000 tokens |

Result: ~95% token reduction

Why Tokens Matter

MCP servers send their tool schemas to the LLM on every request. With a 200k token context window:

• Traditional approach: 15-20k tokens just for schema, leaving less room for actual work
• OpenAPI-driven: ~500 tokens, leaving the context window for your data

How It Works

Instead of hardcoding all tools:

// 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

The schema is loaded from the OpenAPI spec at startup, not hardcoded in the tools.

Inspiration

This project builds on two key inspirations:

1. ProxmoxMCP-Plus — The original 35-tool Python MCP server for Proxmox VE. It proved the full API surface area but carried high token overhead.

2. limehawk/dokploy-mcp — Demonstrated that a 2-tool OpenAPI-driven pattern could dramatically reduce token costs while maintaining full API coverage.

The proxmox-mcp-openapi takes the best of both: the dynamic OpenAPI approach from dokploy-mcp applied to Proxmox, with the additional SSH-based container command execution tools carried over from ProxmoxMCP-Plus.

Architecture Pattern

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

Architecture

• 2 core tools + 2 execution tools
• OpenAPI-driven: 480 operations dynamically loaded from spec
• TypeScript: Type-safe, compiled to JavaScript
• Pure REST API: No Proxmox Perl library dependencies
• SSH key auth for container commands (no API token needed for LXC exec)
• Exec tools carried over from the original ProxmoxMCP-Plus (SSH+pct for LXC, QEMU agent for VMs)

OpenAPI Spec

Includes the Proxmox VE API v2 specification with 480 operations across:

• cluster (122 operations)
• nodes (311 operations)
• storage (5 operations)
• access (36 operations)
• pools (5 operations)
• version (1 operation)

Troubleshooting

"Access denied" on container command

1. Verify SSH key added to Proxmox Web UI → Permissions → SSH Keys
2. Verify container is running (not stopped)
3. Test SSH manually: ssh -i ~/.ssh/proxmox_mcp root@<proxmox-host>

"SSH connection timeout"

1. Check node parameter is correct (use node name like pve, not IP)
2. Verify SSH is running on Proxmox node
3. Check firewall allows port 22

API returns 401/403

1. Verify token format: user@realm!tokenid=secret (not just the UUID)
2. Check token has appropriate permissions in Proxmox

VM command fails with 596

• QEMU agent doesn't support shell features (pipes, redirects)
• Use proxmox-api directly with input-data for stdin

VM command fails with 404

• QEMU guest agent not installed or not running inside the VM
• Install with: apt install qemu-guest-agent (Linux) or enable via Hyper-V/VMware tools

License

MIT