proxmox-mcps

A Model Context Protocol server that exposes your Proxmox VE cluster to AI assistants (Claude Code, Cursor, Windsurf, …). VMs, containers, storage, network, HA, replication, SDN, node admin — 195 tools over stdio, HTTP+SSE, or streamable HTTP.

User-confirmation gates every destructive call. No silent deletes.

Why

Proxmox has no first-class AI surface. Existing bridges are usually a thin wrapper around one or two endpoints. This server exposes the entire Proxmox API surface — VMs and containers, lifecycle, diagnostics, console access, replication, SDN, HA, cluster jobs, node admin — and wraps every destructive call behind an explicit yes/no prompt the model has to relay to you.

• 195 tools across 9 functional areas (see Tool catalog)

• 3 transports — stdio for Claude Code, streamable HTTP for remote clients, SSE legacy

• Approval-gated destructive ops — delete_vm, wipe_node_disk, apply_sdn, … wait for you to type yes

• SSRF guard for server-side downloads (URL allowlist, RFC1918 / loopback rejection)

• Pluggable job store — in-memory (default) or SQLite for tracking long-running operations across restarts

• QEMU guest agent — exec inside the guest, fstrim, fsinfo, hostname, OS info, users, network

• SSH-backed execute_container_command — runs pct exec on the host to drop into a container

Related MCP server: Proxmox MCP Server

Install

From npm

# One-off run (always picks the latest published version)
npx proxmox-mcps

# Or install globally
npm install -g proxmox-mcps
proxmox-mcps

The package ships three binaries:

From source

git clone https://github.com/ngocdd/proxmox-mcps.git
cd proxmox-mcps
npm install
cp .env.example .env       # then fill in host + API token
npm run check-config       # validates your env without starting the server
npm run build              # tsc → dist/
npm start                  # node dist/index.js

Configure

1. Get a Proxmox API token

Proxmox UI → Datacenter → Permissions → API Tokens → Add

• User: root@pam

• Token ID: mcp

• Uncheck "Privilege Separation" (so the token inherits the user's full privileges)

• Copy the generated UUID — that goes into PROXMOX_TOKEN_VALUE

2. Wire it into Claude Code

Install at user scope so the same proxmox server follows you across every project:

claude mcp add proxmox --scope user \
  -e PROXMOX_HOST=proxmox.example.com \
  -e PROXMOX_PORT=8006 \
  -e PROXMOX_USER=root@pam \
  -e PROXMOX_TOKEN_NAME=mcp \
  -e PROXMOX_TOKEN_VALUE=<uuid> \
  -e PROXMOX_VERIFY_SSL=false \
  -e PROXMOX_DEV_MODE=true \
  -- npx -y proxmox-mcps

--scope user writes to ~/.claude.json (or ~/.config/claude/ on Linux). Use --scope project to commit a .mcp.json entry, or --scope local for a one-off project-only entry.

Restart Claude Code. Verify with /mcp — you should see proxmox with 195 tools.

Inspect or remove later:

claude mcp list                # show all configured servers
claude mcp get proxmox         # show env vars + command
claude mcp remove proxmox      # delete the entry

A drop-in .mcp.json snippet is in .mcp.json.example.

3. Or use any other MCP client

The server speaks the standard MCP protocol over three transports. Pick one via MCP_TRANSPORT:

For STREAMABLE / SSE the server listens on MCP_HOST:MCP_PORT and exposes /mcp (JSON-RPC) plus /health.

Tool catalog

195 tools, grouped by surface. Run proxmox-mcps-print-tools for the canonical list with risk classifications.

Risk profile (auto-discovered by print-tools):

Audit-only logging for medium-risk tools is independent of the destructive gate. See Safety model.

Safety model

Destructive & high-risk tools

Any tool classified high or destructive does not run immediately. The server returns a confirmation prompt that the model must show you:

⚠️  Confirmation required: 'delete_vm' is DESTRUCTIVE and cannot be undone.
Target: node=pve, vmid=100
Ask the user to reply 'yes' to proceed, or anything else to cancel.
If they confirm, re-invoke this tool with `confirm: true` added to the arguments.

You reply "yes", the model calls the same tool again with confirm: true, and the operation proceeds. Every destructive action is gated behind an explicit, visible human yes/no.

To skip the prompt for fully trusted automation:

PROXMOX_DANGEROUSLY_ALLOW_DESTRUCTIVE=true

Audit-only logging for medium-risk tools is independent:

PROXMOX_MCP_AUDIT_ONLY=true

Inspect the risk registry at any time:

proxmox-mcps-print-tools            # all 195 tools with risk levels
proxmox-mcps-print-tools destructive # only the 25 destructive ones

SSRF guard for server-side downloads

download_iso (and any future *_from_url tool) hands the URL to Proxmox, which fetches it server-side. Before that happens, the URL is checked:

• Schemes must be in PROXMOX_DOWNLOAD_ALLOWED_SCHEMES (default: http,https).

• Hosts are resolved and rejected if they fall in RFC1918, RFC4193, loopback, link-local, CGNAT, multicast, or any other reserved range. The Proxmox host cannot be turned into an SSRF proxy against your internal network.

• An optional operator allowlist (PROXMOX_DOWNLOAD_ALLOWED_HOSTS) supports suffix (.corp.example), bare-IP, or CIDR matches.

See .env.example for the full reference.

VM config allowlist

update_vm_config rejects keys that can attach host PCI/USB devices, override SMBIOS, or change the QEMU machine type — see src/safety/vm-config-allowlist.ts.

Environment reference

All variables can be passed inline, in .env, or as MCP server env vars. See .env.example for the canonical list with defaults.

PROXMOX_VERIFY_SSL=false requires PROXMOX_DEV_MODE=true — the server refuses to start otherwise.

Development

git clone https://github.com/ngocdd/proxmox-mcps.git
cd proxmox-mcps
npm install
npm run dev               # tsx watch mode
npm run build             # tsc → dist/
npm test                  # 179 unit tests
npm run lint              # eslint
npm run format:check      # prettier

Updating dependencies

npm outdated              # see available updates
npm update                # safe patch + minor bumps
npm audit                 # known CVEs
npm audit fix             # safe security fixes

Native deps (better-sqlite3, ssh2, …) need install scripts. The repo's .npmrc carries the npm 11+ allowlist. If you add a new native dep, append its name to allow-scripts[] there.

Releasing

1. Bump version in package.json.

2. npm test && npm run build.

3. git tag v<version> && git push --tags.

4. npm publish.

Project layout

src/
  index.ts                entry point (stdio / streamable / sse)
  server.ts               MCP server factory
  config/                 env schema (zod) + typed config
  format/                 response formatters
  jobs/                   long-running job tracking (memory + sqlite)
  log.ts                  pino logger
  proxmox/                API client + path helpers
  safety/                 risk registry + approval policy + URL guard
  security/               auth + secret redaction
  ssh/                    SSH client for pct exec
  tools/                  one file per tool group
    vm/                   crud, config, diagnostics, migration, console
    container/            crud, config, diagnostics, migration, console
    cluster, node, storage, tasks, jobs,
    snapshot, backup, backup-schedule, iso,
    pools, ha, replication, sdn,
    node-admin, node-services, node-network, node-disks, node-certs,
    storage-admin
  cli/                    check-config, print-tools
tests/
  unit/                   vitest unit suite (179 tests)
  integration/            end-to-end (gated by PROXMOX_E2E=1)

Security

• Destructive calls require an explicit confirm: true from the model after a user-typed "yes".

• URL guard rejects private/loopback hosts for server-side downloads.

• VM config allowlist blocks keys that can attach host devices or change machine type.

• Logs redact token UUIDs and SSH passwords.

Found a vulnerability? Please email ngocdd94@gmail.com rather than filing a public issue.

Contributing

Issues and PRs welcome. For anything beyond a typo:

1. Open an issue first describing the change.

2. New tools must register a risk level in src/safety/risk.ts (low / medium / high / destructive).

3. New env vars must be added to both src/config/env.ts (zod schema) and .env.example.

4. Run npm test && npm run lint && npm run build before opening the PR.

Acknowledgments

• Built on @modelcontextprotocol/sdk.

• The Proxmox API client uses axios with p-retry for transient errors.

• Long-running job tracking uses better-sqlite3 when persistence is enabled.

• Container command execution uses ssh2 to shell out to pct exec on the host.

License

MIT © Proxmox MCP Contributors