proxmox-mcps

MCP server for Proxmox VE — let your AI assistant run the cluster.

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

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:

Binary	Purpose
proxmox-mcps	MCP server (the thing you wire into Claude Code / your client)
proxmox-mcps-check-config	Validate .env / env vars without starting the server
proxmox-mcps-print-tools	Print every registered tool (or just the destructive ones)

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:

Transport	When to use
STDIO	Default. Local clients (Claude Code, Cursor, Windsurf)
STREAMABLE	Remote clients, modern MCP-over-HTTP
SSE	Legacy SSE-only clients

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.

Group	Count	Highlights
Cluster status	1	get_cluster_status
Pools	5	CRUD + get_pool
HA	11	Resources + groups + migrate-on-fail
VM (QEMU)	43	Lifecycle, config, diagnostics, console (VNC/SPICE/termproxy/monitor), migration, 12 QEMU guest-agent tools
Container (LXC)	27	Lifecycle, config, diagnostics, SSH-backed execute_container_command, console, migration
Snapshots	4	list/create/delete/rollback_snapshot
Backups	13	On-demand + scheduled (vzdump) jobs + restore + prune
ISO / templates	4	List / download / delete (URL-guarded)
Tasks & jobs	8	Proxmox task log + long-running MCP job tracking
Storage	5	list / get / create / update / delete (lvm, zfs, nfs, cifs, pbs, dir, …)
Replication	7	ZFS replication jobs CRUD + status
SDN	21	Controllers / zones / vnets / subnets + apply_sdn
Node admin	46	apt · DNS · hosts · time · config · journal · syslog · pvereport · systemd services · network (bonds/bridges/VLANs/OVS) · disks + ZFS · bulk start/stop/migrate · subscription · certificates

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

Risk	Count	Behaviour
low	79	Runs immediately. Read-only / inspection tools.
medium	72	Runs immediately. State-changing but recoverable.
high	19	Confirmation prompt (returns a yes/no request to the model).
destructive	25	Confirmation prompt + irreversible — extra warning.

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.

Var	Required	Default	Purpose
PROXMOX_HOST	✅	—	Proxmox API hostname / IP
PROXMOX_PORT		8006	Proxmox API port
PROXMOX_USER	✅	—	API user (user@realm)
PROXMOX_TOKEN_NAME	✅	—	Token ID
PROXMOX_TOKEN_VALUE	✅	—	Token secret UUID
PROXMOX_VERIFY_SSL		true	Set false only with self-signed certs
PROXMOX_TIMEOUT_MS		30000	Per-request timeout
PROXMOX_SERVICE		PVE	PVE / PMG / PBS
PROXMOX_DEV_MODE		false	Required when PROXMOX_VERIFY_SSL=false
PROXMOX_DANGEROUSLY_ALLOW_DESTRUCTIVE		false	Skip confirmation prompts for high/destructive tools
PROXMOX_MCP_AUDIT_ONLY		false	Audit-log every medium-risk call
LOG_LEVEL		info	debug / info / warn / error
LOG_PRETTY		false	Use pino-pretty (dev only)
PROXMOX_MCP_RETRY_MAX		3	Retries on transient API errors
PROXMOX_MCP_RETRY_BASE_MS		200	Retry backoff base
PROXMOX_MCP_JOB_TTL_HOURS		24	Long-running job retention
PROXMOX_MCP_JOB_STORE		memory	memory or sqlite
PROXMOX_MCP_JOB_SQLITE_PATH		./proxmox-jobs.sqlite3	SQLite job store path
MCP_TRANSPORT		STDIO	STDIO / SSE / STREAMABLE
MCP_HOST		127.0.0.1	HTTP bind address
MCP_PORT		8000	HTTP listen port
PROXMOX_SSH_USER		root	SSH user for pct exec
PROXMOX_SSH_PORT		22	SSH port
PROXMOX_SSH_KEY_FILE		—	Path to SSH private key
PROXMOX_SSH_PASSWORD		—	SSH password (prefer key)
PROXMOX_SSH_HOST_OVERRIDES		—	JSON map of node → ssh host
PROXMOX_SSH_KNOWN_HOSTS_FILE		—	Path to known_hosts
PROXMOX_SSH_STRICT_HOST_KEY_CHECKING		true	Reject unknown host keys
PROXMOX_DOWNLOAD_ALLOWED_SCHEMES		http,https	URL schemes for download_iso
PROXMOX_DOWNLOAD_ALLOWED_HOSTS		—	Optional allowlist (suffix / IP / CIDR)

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 [email protected] 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