proxmox-mcp

proxmox-mcp is a safety-gated, local stdio Model Context Protocol server for the Proxmox VE API. It is launched as a process by an MCP host; it is not an HTTP service and does not expose an HTTP endpoint.

Status — current release: v0.1.1. The canonical distribution is the GitHub Release archive and its SHA-256 checksum. No npm package is provided or published.

Install the released Proxmox MCP

For a local stdio installation, use the checksum-verified GitHub Release archive:

• GitHub Release v0.1.1
• Archive asset
• Checksum asset

There is no npm package. The LobeHub Marketplace listing describes capabilities; it is not the local installation source. ClawHub is not currently published because a publicly installable OpenClaw wrapper/listing is not available.

Quick install

Download the v0.1.1 archive and checksum from GitHub Releases, verify them, and extract the archive. Do this on the machine where the MCP host will run.

curl -fLO https://github.com/Theorvane/proxmox-mcp/releases/download/v0.1.1/proxmox-mcp-0.1.1.tar.gz
curl -fLO https://github.com/Theorvane/proxmox-mcp/releases/download/v0.1.1/proxmox-mcp-0.1.1.tar.gz.sha256
shasum -a 256 -c proxmox-mcp-0.1.1.tar.gz.sha256
tar -xzf proxmox-mcp-0.1.1.tar.gz
cd proxmox-mcp-0.1.1

The archive requires Node.js >=22. Supply credentials through the environment; the values below are placeholders, not working credentials.

export PROXMOX_BASE_URL='https://proxmox.example:8006'
export PROXMOX_TOKEN_ID='user@realm!token-name'
: "${PROXMOX_TOKEN_SECRET:?set PROXMOX_TOKEN_SECRET in the environment}"
./proxmox-mcp

./proxmox-mcp is a stdio process. Register or configure that command, its working directory, and the three environment variables in your MCP host; starting it in a terminal alone does not make it available to a client. For the archive layout and installation details, see the GitHub Release installation guide.

Configuration

Only these environment variables are used:

Variable	Required	Meaning
PROXMOX_BASE_URL	Yes	HTTPS origin for the Proxmox VE API, for example https://proxmox.example:8006.
PROXMOX_TOKEN_ID	Yes	Proxmox API token identifier.
PROXMOX_TOKEN_SECRET	Yes	Proxmox API token secret; provide it only through the local process environment.

TLS certificate verification is always enabled. PROXMOX_TLS_VERIFY=false is rejected at startup; do not use it. If the Proxmox endpoint uses a private CA, trust that CA in the host trust store. See configuration for the full policy.

Capabilities

The server provides a focused set of Proxmox VE operations. MCP hosts discover the exact schemas and tool descriptions at connection time.

Area	Implemented capabilities
Inventory	Cluster version and resources; node status; node storage; QEMU and LXC inventory; task inventory and task status.
QEMU and LXC lifecycle	Start, graceful shutdown, stop, and reboot QEMU VMs and LXC containers.
Creation and configuration	Create and configure QEMU VMs and LXC containers.
Storage	Resize a QEMU disk.
Protected actions	Delete a QEMU VM or LXC container, delete an unused QEMU disk, and force-stop a QEMU VM.

Tool names, inputs, outputs, and node-name validation rules are documented in the tool contract.

Safety model

Control	Behavior
Destructive-action gate	qemu_delete, lxc_delete, qemu_delete_disk, and qemu_force_stop require an exact node, exact vmid, and confirm: true before any Proxmox request is made.
Target validation	Node names are constrained to a supported Proxmox hostname label, and dynamic API path segments are encoded.
Authorization	Proxmox RBAC remains authoritative. This server does not grant permissions beyond the API token.
TLS	HTTPS is required and certificate verification cannot be disabled.

Deletion, unused-disk removal, and force-stop can be non-recoverable. Review targets carefully and give the token only the Proxmox permissions it needs. See the complete safety guidance.

OpenClaw local skill

The merged dev codebase contains an OpenClaw skill at skills/proxmox-mcp-openclaw/. It is a local skill, not a generic OpenClaw plugin. Use its local SKILL.md instructions.

Choose a new absolute target directory—the target must not already exist. First inspect the credential-free plan:

node skills/proxmox-mcp-openclaw/scripts/install.mjs --dry-run /absolute/path/to/proxmox-mcp

With the three configuration variables exported in the shell, install and register it:

node skills/proxmox-mcp-openclaw/scripts/install.mjs /absolute/path/to/proxmox-mcp

The installer verifies the immutable v0.1.1 release and its checksum, then invokes the supported openclaw mcp add command only after preflight succeeds. It does not log or store credentials.

Operational boundaries

• This is a local stdio MCP integration, not a hosted service or a replacement for Proxmox access controls.
• The server does not make a Proxmox request until an MCP client calls a tool. Installation and documentation examples do not call a real Proxmox API.
• Keep credentials out of repositories, shell history where practical, and shared configuration files. Use a least-privilege Proxmox API token.
• Obtain releases only from Theorvane/proxmox-mcp GitHub Releases and verify the published SHA-256 checksum before running the archive.

Documentation

• Configuration
• Safety
• API and tool contract
• GitHub Release installation
• Contributing
• Security

Verification and contributing

Contributors work from an issue-numbered branch based on dev, open pull requests to dev, and promote only reviewed dev to main. GitHub Release archives are the only distribution channel. See CONTRIBUTING.md.

Maintainers can run the same local verification commands used by the project:

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run release:archive
npm run verify:release-archive
npm run validate:docs
npm run validate:governance
npm run validate:release
npm audit --omit=dev --audit-level=high
git diff --check

License

This project is licensed under the terms in LICENSE.