Proxmox MCP Bridge

A policy-aware Model Context Protocol server for Proxmox VE. It maps the API schema installed on the host, provides compact and expanded MCP tool modes, supports Streamable HTTP and stdio, and adds guarded host command and filesystem operations.

The first release targets Proxmox VE 9.x. Portability to other releases is experimental.

Capabilities

• Complete API discovery, description, and invocation from the official local apidoc.js schema.
• Automatic schema refresh after Proxmox updates with last-known-good fallback.
• Curated node health, disk, network, journal, updates, guest configuration, snapshots, backups, consoles, task lifecycle, service, command, and file-transfer tools.
• Optional endpoint-per-tool expansion via PMCP_TOOL_MODE=expanded.
• Per-person read-only, operator, admin, root, or deterministic custom policies.
• Conversational onboarding through the proxmox_onboarding MCP prompt.
• Two-confirmation, one-operation, five-minute break-glass handling for the protected model repository.

Install on Proxmox

Prerequisites:

• A Proxmox VE 9.x host and root shell.
• Internet access during installation for Debian packages and npm dependencies.
• Optional Tailscale installed, logged in, and active if Tailnet access is selected.
• A private RFC1918 address if private-LAN access is selected.

git clone https://github.com/jebinjollyabraham/proxmox-mcp-bridge.git /root/tools/proxmox-mcp-bridge
cd /root/tools/proxmox-mcp-bridge
./scripts/install.sh

The interactive installer asks whether this installation should be reachable through localhost, Tailscale, a private LAN, or both Tailscale and LAN. It detects the current host's values and writes them only to /etc/proxmox-mcp-bridge/service.env; no installation-specific hostname or address belongs in this repository.

The installer creates a dedicated Proxmox service identity, system users, systemd units, a local TLS CA, and the first root-profile MCP key. Its one-time plaintext is written to /root/proxmox-mcp-initial-key.json with mode 0600; only the scrypt hash remains in bridge state. The MCP bearer key is separate from the internal Proxmox API token.

Endpoints:

• Tailnet example: https://your-proxmox-host.your-tailnet.ts.net/mcp
• Private-LAN example: https://192.168.1.100:9444/mcp
• Loopback: http://127.0.0.1:8765/mcp

The installer prints the actual endpoints for that installation. It adds the Tailnet /mcp route without resetting other Tailscale Serve routes. LAN clients must trust /etc/proxmox-mcp-bridge/pki/ca.crt. The bridge never intentionally binds to a public address.

For unattended installation, set PMCP_SETUP_MODE to local, tailscale, lan, or both. PMCP_LAN_HOST is required for LAN modes unless a private address can be detected. PMCP_TAILSCALE_HOST can override Tailscale DNS-name detection.

Key management

proxmox-mcp key create --name alice --profile read-only
proxmox-mcp key create --name operator --profile operator --expires 2027-01-01T00:00:00Z
proxmox-mcp key list
proxmox-mcp key rotate alice
proxmox-mcp key revoke alice

Key secrets are returned once. Rotation atomically revokes the prior key. Use the onboarding and policy tools to create a custom policy, activate its digest, then bind a key with --profile custom --policy POLICY_ID.

Automatic API alignment

At startup the bridge extracts only the JSON array assigned to const apiSchema in /usr/share/pve-docs/api-viewer/apidoc.js; it never evaluates JavaScript. The normalized registry records method, template path, parameter and return schemas, permissions, token support, risk, and a deterministic expanded tool name.

proxmox-mcp-schema.path watches the official schema. A valid update replaces the cache and restarts the bridge. A malformed update leaves the last-known-good cache active and surfaces the error through proxmox_schema_status and /healthy.

Safety boundary

No installation or test command writes to or deletes /mnt/model-repo or its logical volume. Ordinary bridge processes see the model mount read-only and known model block-device paths hidden. Model mutation requires an exact structured operation, two separate confirmation phrases, and a signed one-shot root runner.

A root MCP key remains equivalent to a highly privileged automation credential. Read the security model before distributing one.

Development

npm ci
npm test

The tests cover schema extraction, deterministic expanded names, key hashing, rotation and revocation, policy precedence, and the model guard. The real model repository is never used as a destructive test target.

License

Apache-2.0