Proxmox VE MCP

Secure, API-token authenticated MCP access to the Proxmox VE HTTP API. See CONTRIBUTING.md for local checks and SECURITY.md for private vulnerability reporting.

An MCP server that connects to Proxmox VE using an API token. It exposes every HTTP API path, not a hardcoded subset of VM operations, and provides searchable API documentation, multipart uploads, and streamed downloads.

VMs, LXC, nodes, clusters, storage, backups, snapshots, migration, replication, networking, SDN, firewall, Ceph, HA, pools, users, ACLs, metrics, and tasks all use the same API tools. New endpoints work without a server update.

Install

Requires Bun 1.3 or newer.

cd /absolute/path/to/proxmox-mcp
bun install --frozen-lockfile
bun run build

This project uses MCP stdio: your MCP client starts a local process which connects over HTTPS to your Proxmox host. It does not expose an unauthenticated MCP HTTP listener. File-transfer paths refer to the machine running this process, not the Proxmox node.

Related MCP server: Proxmox MCP Server

Create a Proxmox API token

1. In the Proxmox UI, create or select a user under Datacenter > Permissions > Users.

2. Under Datacenter > Permissions > API Tokens, add a token for that user.

3. Save its token ID (mcp@pve!assistant) and the secret shown once at creation.

4. Grant the user the required ACL role and path. With Privilege Separation enabled, grant the token permissions too: effective access is the intersection of the user's and token's ACLs.

For broad administration, assign the Administrator role at / with propagation to both the user and the privilege-separated token. To limit access, assign narrower roles and paths instead. A token cannot exceed its owner's privileges.

Coverage is not permission bypass. Proxmox explicitly disallows API tokens on some endpoints (allowtoken: 0), and some operations require a particular user, such as root@pam. This server exposes those endpoints but returns Proxmox's rejection when token authentication is insufficient. A token alone cannot provide literally every Proxmox function. It does not add password/ticket login, SSH access, or an interactive VNC/SPICE/terminal WebSocket client. HTTP console/ticket endpoints remain callable where Proxmox permits them.

Connect your MCP client

Add this to your client's MCP configuration, replacing the paths and credentials. Use the absolute Bun path returned by which bun if the client does not inherit your shell's PATH.

{
  "mcpServers": {
    "proxmox": {
      "command": "/absolute/path/to/bun",
      "args": ["/absolute/path/to/proxmox-mcp/dist/index.js"],
      "env": {
        "PROXMOX_URL": "https://pve.example.com:8006",
        "PROXMOX_TOKEN_ID": "mcp@pve!assistant",
        "PROXMOX_TOKEN_SECRET": "YOUR_TOKEN_SECRET",
        "PROXMOX_VERIFY_TLS": "true"
      }
    }
  }
}

Restart/reconnect the MCP client. Ask it to call proxmox_get with {"path":"/version"}, then {"path":"/nodes"}. These calls verify the connection and token permissions.

For development, copy .env.example to .env, fill it in, and run bun start from the project directory. Bun loads .env automatically. The process waits for MCP input; it is not an interactive command prompt. Keep secrets in the client's environment/secret store or a private environment file, not in tool arguments.

OmO installation on this machine

This installation is an explicit native OmO skill at ~/.agents/skills/proxmox-ve/. Invoke /skill:proxmox-ve (or $proxmox-ve) in a fresh session before calling a Proxmox tool. Its MCP sidecar uses --env-file=/Users/cminseo/proxmox-mcp/.env, so credentials stay in the ignored, mode-0600 project file rather than OmO's global MCP configuration. The global configuration deliberately has no proxmox entry: that avoids a system-config collision and keeps tool activation skill-owned.

After explicit activation, /mcp status should report proxmox connected with six tools. OmO maps them to:

• mcp_proxmox_proxmox_get

• mcp_proxmox_proxmox_request

• mcp_proxmox_proxmox_upload

• mcp_proxmox_proxmox_download

• mcp_proxmox_proxmox_search_endpoints

• mcp_proxmox_proxmox_describe_endpoint

The read-only OmO integration check is:

bun ~/.omo/evidence/proxmox-omo-integration-20260922.mjs --live

It calls only three read-only endpoints: /version, /nodes, and /access/permissions. Without --live, it loads the skill sidecar and exercises them against a local fixture. The deployed check uses /access/permissions to confirm the token's effective ACLs; it makes no changes. The installed host can still connect a skill-declared server while collecting its catalog, and tool search can activate tools, so the skill guarantees explicit discovery guidance rather than a hard process or prompt isolation boundary.

Settings

Prefer trusting your cluster's CA using PROXMOX_CA_FILE. For a self-signed lab server you can explicitly set PROXMOX_VERIFY_TLS=false; this affects only this connection, not process-wide TLS. Use HTTPS for remote hosts.

Discovery lazily downloads the official API viewer schema, extracts JSON without executing JavaScript, rejects redirects, limits the source to 8 MiB, and caches one in-flight load plus the parsed catalog until restart. The default documents the current published version, which may differ from your cluster. Point PROXMOX_SCHEMA_URL at version-matched documentation when needed. No Proxmox credentials are sent to the catalog host. Private CA settings apply to API traffic, not the public catalog download.

If documentation is unavailable, API calls still work. Consult your cluster's API viewer and supply its concrete paths and parameters directly.

Tools

Paths are relative to /api2/json, start with /, and cannot contain a query or fragment. Put parameters in parameters. Replace template segments with real values. Percent-encode special characters inside identifiers, such as / within a volume ID. Do not double-encode.

Booleans become 1 or 0. GET and DELETE parameters use the query string; POST and PUT use application/x-www-form-urlencoded. Arrays produce repeated keys; when Proxmox expects a comma-separated list, supply a string. Proxmox property strings must also be strings, for example net0: "virtio,bridge=vmbr0" rather than a nested JSON object. Null and object parameter values are rejected.

JSON responses retain the Proxmox envelope (data, total, etc.) in both MCP text and structured content. API failures return isError: true with HTTP status and details. The configured token ID and secret are redacted from MCP results and errors. The server never automatically retries API operations, and never follows API redirects.

JSON and text API responses are capped at 512 KiB before MCP serialization; use proxmox_download for larger raw artifacts. Upload and download are disabled until PROXMOX_FILE_ROOTS names dedicated directories; canonical paths and symlinks outside those roots are rejected, and group- or world-writable roots or upload-parent directories are refused. Uploads are read through a pinned file descriptor after validation, so later pathname replacement cannot switch the uploaded file. Write tools can perform destructive administration if the token allows it; they do not add a confirmation gate beyond the MCP client's own tool approval controls. Download files use exclusive creation (no overwrites), mode 0600, and partial files are removed on failure.

Find and call an endpoint

{
  "name": "proxmox_search_endpoints",
  "arguments": { "query": "qemu snapshot", "method": "POST", "limit": 10 }
}

{
  "name": "proxmox_describe_endpoint",
  "arguments": { "path": "/nodes/{node}/qemu/{vmid}/snapshot", "method": "POST" }
}

{
  "name": "proxmox_request",
  "arguments": {
    "method": "POST",
    "path": "/nodes/pve/qemu/100/snapshot",
    "parameters": { "snapname": "before-upgrade", "description": "Before upgrade" }
  }
}

Start a VM and check its task

{
  "name": "proxmox_request",
  "arguments": { "method": "POST", "path": "/nodes/pve/qemu/100/status/start" }
}

A returned data: "UPID:..." means the operation was submitted, not that it succeeded. Use the actual returned UPID:

{
  "name": "proxmox_get",
  "arguments": { "path": "/nodes/pve/tasks/UPID_FROM_THE_RESPONSE/status" }
}

Completion requires status: "stopped" and exitstatus: "OK". Inspect /nodes/pve/tasks/UPID_FROM_THE_RESPONSE/log for failures. Task listing, cancellation, and log pagination are also available through ordinary API calls.

Upload an ISO

{
  "name": "proxmox_upload",
  "arguments": {
    "path": "/nodes/pve/storage/local/upload",
    "file_path": "/absolute/path/inside/PROXMOX_FILE_ROOTS/debian.iso",
    "parameters": { "content": "iso" }
  }
}

For large images, Proxmox's /nodes/{node}/storage/{storage}/download-url API may be preferable: call it with proxmox_request to have the node download the image directly.

Download a raw response

{
  "name": "proxmox_download",
  "arguments": {
    "path": "/nodes/pve/rrd",
    "parameters": { "ds": "cpu", "timeframe": "hour" },
    "destination": "/absolute/path/inside/PROXMOX_FILE_ROOTS/new-chart.png"
  }
}

The destination's parent directory must already exist. Use response_format: "text" on proxmox_request for endpoints returning text instead of JSON.

Verification

bun run typecheck
bun test
bun run build
MCP_TEST_ENTRY=../dist/index.js bun test test/stdio.test.ts

Tests require openssl on PATH to generate temporary TLS certificates. They use local HTTP/HTTPS fixtures and the real MCP SDK, including a spawned stdio process, and cover CA trust, cancellation and streaming deadlines. They do not create resources on a Proxmox cluster. A live cluster and its credentials are required to verify deployment-specific ACLs and actual VM/storage operations.

The installed OmO configuration was additionally verified read-only against PVE 9.1.6 on 2026-09-22: all six tools registered through OmO's native MCP service, /version and /nodes succeeded, and /access/permissions returned 846 effective grants for the dedicated token. No mutating API operation was performed, so VM/storage/network changes remain unverified by design.

Troubleshooting: 401 usually means a bad/expired token or disabled user; 403 means insufficient effective permissions or an endpoint that rejects API tokens. TLS errors usually require your cluster CA. Discovery failure does not imply the Proxmox API is down.

References: Proxmox API authentication and encoding, API viewer, MCP TypeScript SDK.

The tested old/new release and subscription-channel boundaries are recorded in docs/compatibility.md.