A local MCP (Model Context Protocol) server
that lets Claude Desktop (or any MCP-compatible client) manage a
Proxmox VE cluster through its REST API using token authentication.
Tested with Proxmox VE 9.1.9 on a single-node setup. Multi-node clusters
should work — every tool accepts a parameter.
Local MCP server for managing Proxmox VE clusters from Claude Desktop. Token-auth, 15 tools, GPL v3.
The package exposes 52 tools, grouped by category below. Read-only
tools are safe to call automatically; every state-changing tool requires
confirm=true, and tools that destroy persistent data additionally
require i_understand_data_loss=true (see Built-in safety).
Token-efficiency features (v1.0):
proxmox_health_overview answers "how is the server?" in one call.
List filters — e.g. proxmox_list_vms(status='running', node=...),
proxmox_list_backups(vmid=...) — return only what you asked for.
fields projection — with response_format='json', pass
fields=['vmid','name','status'] to strip every other key.
wait_seconds on task-launching tools (power, snapshot, backup,
restore, clone, move-disk, LVM/ZFS provisioning): the tool polls the
Proxmox task and returns the final result inline, saving a follow-up
status call.
JSON output is compact and hard-capped; oversized lists are truncated
at the item level and stay valid JSON ({"_truncated_items": N} marker).
Overview & nodes (read-only)
Tool
Description
proxmox_health_overview
One-call summary: node load, guest states, storage fill levels, ZFS pool health
proxmox_list_nodes
List all nodes in the cluster with status, uptime, CPU and memory usage
proxmox_get_node_status
Detailed status for one node: CPU model, kernel, load average, disk, swap
VMs & containers
Tool
Description
proxmox_list_vms
List VMs/CTs; filters: node, vmid, status, guest_type (read-only)
proxmox_get_vm_status
Detailed runtime metrics for a single VM/CT (read-only)
proxmox_vm_power
Power action: action='start' | 'shutdown' | 'stop' | 'reboot' (guest type auto-detected)
proxmox_resize_vm
Change RAM (memory_mb) and/or CPU cores of a VM/CT
Guest creation (from scratch)
Tool
Description
proxmox_create_vm
Create a QEMU VM: core hardware (cores/sockets/memory/ostype), one virtio-scsi boot disk, one virtio NIC, optional install ISO (boots from the CD first). Requires confirm=true; dry_run=true previews the exact payload without creating.
proxmox_create_container
Create an LXC container from a template: rootfs, one NIC (dhcp or static CIDR), root access via password and/or ssh_public_key, unprivileged by default, optional nesting. Requires confirm=true; dry_run=true previews (secrets masked).
Snapshots
Tool
Description
proxmox_list_snapshots
Snapshots for a specific VM/CT (read-only)
proxmox_snapshot
action='create' | 'rollback' | 'delete'. Rollback loses state newer than the snapshot; delete also needs i_understand_data_loss=true
Backups
Tool
Description
proxmox_list_backups
Backup files on a storage, newest first; filters: vmid, limit (read-only)
proxmox_create_backup
Create a backup with selectable mode and compression
proxmox_restore_backup
Restore a VM/CT from a backup archive. Refuses to overwrite an existing VMID unless force=true and i_understand_data_loss=true. dry_run=true previews the endpoint + payload and reports whether it would be a fresh restore or an overwrite.
Storage (read-only)
Tool
Description
proxmox_list_storage
Storage pools on a node with usage info
proxmox_storage_usage_detail
Per-storage content breakdown: items by type with totals, plus top-N largest items. Useful for capacity planning ("which VM is eating my backup storage?").
Disk / LVM / ZFS inventory (read-only)
Tool
Description
proxmox_list_disks
Physical disks on a node: model, size, type, health, usage
proxmox_get_disk_smart
SMART health and attributes for one physical disk
proxmox_list_lvm
LVM volume groups and logical volumes on a node
proxmox_list_lvm_thin
LVM-thin pools on a node
proxmox_list_zfs
ZFS pools on a node with capacity/health
proxmox_get_zfs_pool
Detailed status of a single ZFS pool
Disk preparation & storage provisioning
Tool
Description
proxmox_disk_prepare
action='wipe' | 'init_gpt' on a disk (destructive). via='auto' (default) uses the REST API and falls back to SSH (wipefs/sgdisk) when the endpoint rejects the API token
proxmox_lvm_manage
action='create_vg' | 'create_thin' | 'destroy_vg' | 'destroy_thin' (destroys are destructive)
proxmox_zfs_pool_manage
action='create' | 'destroy' a ZFS pool (destroy is destructive)
proxmox_list_cluster_storage
List datacenter-level storage configuration (read-only)
proxmox_storage_config
action='add_zfs' | 'add_dir' | 'remove' on datacenter storage entries (remove never touches data)
SSH-backed ZFS ops
These run shell commands on the node over SSH, for operations the API
token can't perform. They need the SSH configuration described in the
Configuration reference.
Tool
Description
proxmox_zfs_dataset
action='create' | 'destroy' a ZFS dataset (recursive destroy needs i_understand_data_loss=true)
proxmox_zfs_property
action='get' | 'set' ZFS properties (set is allow-listed and needs confirm=true)
proxmox_zfs_create_snapshot
Create a ZFS snapshot of a dataset
proxmox_zfs_list_datasets
List ZFS datasets (read-only)
proxmox_zfs_destroy_snapshots_by_pattern
Bulk-delete ZFS snapshots whose name matches a glob pattern. Two-step: dry_run=true (default) lists matches; dry_run=false with confirm=true and i_understand_data_loss=true actually deletes. Capped at max_delete (default 1000).
VM disk / clone / ISO + ZFS status
Tool
Description
proxmox_move_disk
Move a VM disk to another storage
proxmox_clone_vm
Clone a VM/CT to a new VMID. dry_run=true previews the payload without cloning.
proxmox_list_isos
List ISO images available on storages (read-only)
proxmox_zfs_pool_status
zpool status for a pool: health, errors, scrub state (read-only)
proxmox_zfs_scrub
Start a scrub on a ZFS pool
proxmox_zfs_send
ZFS send stream for replication
Guest VM SSH (full shell, audit-logged)
Tool
Description
proxmox_vm_list_hosts
List guest VM aliases registered in vm_ssh_hosts.json (read-only)
proxmox_vm_exec
Run a shell command on a registered guest VM via SSH (uses vm_ssh_hosts.json). Requires confirm=true. Commands matching destructive patterns also require i_understand_data_loss=true, as do wrappers whose content the check can't see (base64/xxd decode, eval or a pipe into a shell/interpreter at any command position — after |, ||, !, then, $(, sudo/env/xargs —, sh -c "$X"); quotes are stripped and $(…), sh -c/ssh/pct exec -- scripts are followed; base64 literals in the command are decoded and checked. A command the check can't parse (an unclosed quote, $( or heredoc, a wrapper option it doesn't know such as sudo -h host or env -S) needs the flag too.
proxmox_vm_read_file
Read a file from a registered guest VM over SSH (read-only)
Proxmox host SSH (full shell, audit-logged)
Tool
Description
proxmox_host_exec
Run an arbitrary shell command on the Proxmox host over SSH. Requires confirm=true. Commands matching destructive patterns also require i_understand_data_loss=true, as do wrappers whose content the check can't see (base64/xxd decode, eval or a pipe into a shell/interpreter at any command position — after |, ||, !, then, $(, sudo/env/xargs —, sh -c "$X"); quotes are stripped and $(…), sh -c/ssh/pct exec -- scripts are followed; base64 literals in the command are decoded and checked. A command the check can't parse (an unclosed quote, $( or heredoc, a wrapper option it doesn't know such as sudo -h host or env -S) needs the flag too. Every call is appended to _host_ssh_audit.log.
proxmox_host_read_exec
Run a single read-only command on the Proxmox host, checked against an allow-list (proxmox_mcp/read_allow.py): listed programs, their read subcommands and their options by exact name — anything unlisted (program, subcommand, option, abbreviation, attached -oX=Y) is refused. Coverage: files/text (cat, head, tail, grep, zcat, stat, du, …), storage (lsblk, findmnt, pvs/lvs/vgs, zpool status/list/iostat, zfs list/get, smartctl, proxmox-boot-tool status), hardware (lspci, lsusb, dmidecode, dmesg), processes/net (ps, ss, lsof, pgrep, ip OBJECT show), services (systemctl status/show/is-active/list-*, journalctl, coredumpctl list/info), Proxmox (pveversion, pct/qm config/list/status, pvesm, pvesh get), packages (dpkg-query, apt list, apt-cache). Inside a CT: pct exec <vmid> -- <command> (the inner command is checked the same way, one level). No pipes, redirects, chaining or substitution; quoted text may contain any character (grep -E 'a|b'). Runs under timeout (host and CT), a 1 GiB heap limit and a 1 MiB output cap. No confirm needed — safe to grant to read-only agents. The same file is homelab-agent-sys's second layer (byte-identical, sha256-pinned).
Audit-log integrity
Tool
Description
proxmox_audit_verify
Verify the tamper-evident hash chain of the SSH audit logs (which='host' | 'vm' | 'all'). Every host/guest shell exec is appended as a hash-chained line (SHA-256, or HMAC-SHA256 when PROXMOX_AUDIT_HMAC_KEY is set); this recomputes the chain and reports INTACT/BROKEN with the first offending line. Set tail=N to also replay the most recent N recorded entries for review. Read-only.
LXC exec
Tool
Description
proxmox_lxc_exec
Run a shell command inside an LXC container via pct exec from the Proxmox host. No SSH inside the CT needed. Requires confirm=true. Commands matching destructive patterns also require i_understand_data_loss=true, as do wrappers whose content the check can't see (base64/xxd decode, eval or a pipe into a shell/interpreter at any command position — after |, ||, !, then, $(, sudo/env/xargs —, sh -c "$X"); quotes are stripped and $(…), sh -c/ssh/pct exec -- scripts are followed; base64 literals in the command are decoded and checked. A command the check can't parse (an unclosed quote, $( or heredoc, a wrapper option it doesn't know such as sudo -h host or env -S) needs the flag too.
proxmox_ct_service_action
Typed shortcut on top of proxmox_lxc_exec: systemctl --no-pager <action> <service> inside a CT. Read-only actions (status, is-active, is-enabled, show) skip confirm; state-changing actions (start, stop, restart, reload, enable, disable, mask, unmask) require confirm=true.
proxmox_ct_log_tail
Read-only tail of a journald unit or log file from inside a CT. Two modes: service (journalctl -u) and file (tail -n). Optional grep server-side filter.
Diagnostics, forensics & cleanup
Tool
Description
proxmox_zfs_list_snapshots
List ZFS snapshots (name, used, referenced, creation) directly via SSH, including transient @vzdump scratch snapshots the PVE config-snapshot API never reports. Filter by dataset and/or contains. (read-only)
proxmox_list_tasks
List recent PVE tasks (vzdump/snapshot/...) with start time, status and UPID. Filter by typefilter, vmid, errors_only. (read-only)
proxmox_get_task_log
Read a PVE task's log lines by UPID — e.g. the exact reason a vzdump run failed. (read-only)
proxmox_list_backup_jobs
List configured vzdump jobs (schedule, storage, vmids, retention) from /cluster/backup. (read-only)
proxmox_cleanup_vzdump_snapshots
Self-heal. Remove leftover @vzdump ZFS snapshots that block a guest's backups (a stale scratch snapshot from an interrupted run makes every later backup fail with dataset already exists). Targets only names ending in @vzdump and skips any younger than min_age_minutes (default 30) so it can never race a running backup. dry_run=true by default; real removal needs dry_run=false + confirm=true.
Built-in safety
Every tool falls into one of three safety classes, enforced by the input
model itself — not just documented:
Class
Gate
Examples
Read-only
none — runs freely
proxmox_health_overview, all list_*/get_*, proxmox_audit_verify, proxmox_host_read_exec
The gates are Pydantic fields defaulting to false, and every input model uses
extra="forbid" — so a forgotten flag, a typo (confirmed=true), or a
malformed value (confirm="maybe") is rejected, never silently treated as
consent. tests/test_safety_gates.py proves a refused mutation issues no HTTP
write call.
PVE-registered snapshots are never raw-destroyed (1.6.0). A snapshot taken
with pct/qm snapshot also has a [name] section in the guest config;
deleting only its ZFS half leaves that section behind, and the next
pct/qm delsnapshot strands the guest in lock: snapshot-delete (it then
won't start). proxmox_zfs_destroy_snapshots_by_pattern,
proxmox_cleanup_vzdump_snapshots and proxmox_host_exec (when the command
contains zfs destroy) read every guest config first and refuse — no flag
overrides it — pointing to pct/qm delsnapshot. Snapshots PVE doesn't know
about (sanoid autosnap_*, ad-hoc zfs snapshot) pass. If /etc/pve can't be
read, they refuse rather than run blind. Limit: proxmox_host_exec only sees
literal <dataset>@<snap> text, so names generated at run time
(zfs list … | xargs zfs destroy) slip through — use the pattern tool, which
checks every match exactly. tests/test_pve_snapshot_gate.py covers it.
Operator approval (mcp ≥ 2.0).confirm=true is a tool argument, so it
proves the model's intent and nothing about the operator's — no part of the
protocol forces the question to reach a human. Where the client offers form
elicitation, proxmox_snapshot also asks the operator directly, using the
resolver injection added in MCP spec revision 2026-07-28: the approval arrives
in a parameter filled by the server, never appears in the model-facing input
schema, and therefore cannot be supplied — or forged — by a tool call. A
declined prompt refuses the call and issues no write, even when the model set
every flag. The question is raised only once the flag gates already pass, so a
missing flag is still refused on the spot without bothering the operator; and on
an SDK or client without elicitation the flags remain the whole gate, exactly as
before.
Read-only first. The read-only set (start with proxmox_health_overview)
carries no gate, so an agent can inspect a node freely; nothing changes state
until an explicit confirm=true call.
dry-run previews. The highest-consequence mutations — proxmox_create_vm,
proxmox_create_container, proxmox_clone_vm and proxmox_restore_backup —
also accept dry_run=true, which returns the exact API call they would make
(secrets masked) without executing it.
Tamper-evident audit. Every host/guest SSH exec is appended to a
hash-chained log (SHA-256, or HMAC-SHA256 with PROXMOX_AUDIT_HMAC_KEY).
proxmox_audit_verify recomputes the chain (INTACT/BROKEN) and, with tail=N,
replays the most recent entries. Before a line is hashed, secrets in the command
and the output previews are masked (1.7.0, proxmox_mcp/redact.py): values of
secret-looking variables in the server's environment become <gizli:NAME>, and
secret-shaped text that was never in that environment (NAME=value with a
secret-ish name, credentials in a URL, Bearer …, PVE/PBS API tokens, PEM
private keys, sk-ant-…/ghp_…/Telegram tokens, a base64 blob hiding any of
these) becomes <gizli>. The log file is created 0600 (a group-writable
log keeps its group bits, e.g. two service uids sharing it), and appends from
concurrent server processes are serialised by a file lock (1.7.2), so several
clients sharing one log keep the chain intact. For a log written
before 1.7.0, audit.rewrite_redacted(path) masks it in place and rebuilds the
chain (an already-broken link stays broken); it takes the same lock, so lines
appended meanwhile are kept, and the file keeps its owner and mode (1.7.3).
It never re-signs a line whose hash doesn't match (1.8.0): by default it
refuses such a log, force=True masks the rest and leaves those lines visibly
broken, and a log where no line verifies (HMAC key not loaded) is refused
either way.
Safety in action — a destructive request is refused, previewed, then
applied only after explicit consent, and stays on the audit trail:
# 1. Restore over an existing guest, force+confirm but no ack -> refused, no write
restore_backup(vmid=101, archive=…, force=true, confirm=true)
-> Refused: requires i_understand_data_loss=true (no HTTP write made)
# 2. Preview first -> see the exact call, nothing changes
restore_backup(vmid=101, archive=…, dry_run=true)
-> DRY RUN — POST /nodes/pve/qemu … Effect: OVERWRITE existing guest.
# 3. Apply only after the user explicitly accepts the data loss
restore_backup(vmid=101, archive=…, force=true, confirm=true,
i_understand_data_loss=true)
-> OK: restore started …
# 4. The exec trail stays verifiable
audit_verify(tail=5) -> 🟢 host: INTACT — 128 chained … + last 5 entries
Requirements
Python 3.11+
A Proxmox VE host you can reach over HTTPS (default port 8006)
A Proxmox API token with the right privileges (see below)
Claude Desktop (or any MCP client)
1. Create a Proxmox API token
The server authenticates with an API token, never with a root password. Tokens
can be revoked individually and limit blast radius.
Log in to the Proxmox web UI.
Go to Datacenter → Permissions → API Tokens.
Click Add:
User: root@pam (or a dedicated user — recommended)
Token ID: mcp-server (any name)
Privilege Separation: keep enabled unless you know you want otherwise
Click Add. A dialog shows the secret value (a UUID) once.
Copy it now; you cannot retrieve it again.
If you keep Privilege Separation enabled, you must also grant the token
permissions. Go to Datacenter → Permissions → Add → API Token Permission:
Path: / (or narrower if you prefer)
API Token: the token you just made
Role: PVEAdmin for full access, or PVEVMAdmin if you only want
VM/CT management
Propagate: checked
You can scope this much more tightly in production. For a homelab / with
PVEAdmin is the simplest.
PROXMOX_HOST=192.168.1.10 # IP or hostname of your Proxmox host
PROXMOX_PORT=8006 # default
PROXMOX_USER=root@pam # the user owning the token
PROXMOX_TOKEN_NAME=mcp-server # the Token ID you chose
PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-... # the secret UUID
PROXMOX_VERIFY_SSL=false # most homelabs use self-signed certs
PROXMOX_TIMEOUT=30
Never commit .env to git. The included .gitignore already excludes it,
but double-check.
4. Smoke test
With the venv active:
python proxmox_mcp.py --help
You should see the tool list and exit cleanly. An import error here means a
dependency didn't install correctly.
Adjust paths for your OS. On Windows, double-backslashes are required inside
JSON strings.
Fully quit Claude Desktop (tray icon → Quit) and reopen it. In a new chat the
Proxmox tools appear under the hammer/connector icon.
First test in chat
Start with a read-only call:
"List my Proxmox nodes."
Claude calls proxmox_list_nodes. You should see a list of nodes with their
status. If you get an authentication error, recheck PROXMOX_TOKEN_VALUE and
the token's permissions.
Then try:
"Show me all VMs."
"What's the status of VM 101?"
"List backups on the local storage of node pve."
Once you're confident the read-only tools work, you can try action tools:
"Reboot VM 101."
Claude will ask you to confirm. After you say yes, it calls
proxmox_vm_power with action='reboot', confirm=true.
Example workflows
Resize a VM and reboot it:
"Set VM 101 to 4 GB of RAM, then reboot it."
Claude calls proxmox_resize_vm with memory_mb=4096, confirm=true, then
proxmox_vm_power with action='reboot', confirm=true, wait_seconds=60.
Quick backup before a risky upgrade:
"Create a snapshot of VM 102 called pre-upgrade with description
'before kernel update'."
Claude calls proxmox_snapshot with action='create', confirm=true.
Inspect health:
"How is the server? Any storage filling up?"
Claude calls proxmox_health_overview — one call covers node load, guest
states, storage fill levels, and ZFS pool health.
Configuration reference
All settings come from environment variables, loaded from .env:
Variable
Default
Description
PROXMOX_HOST
— (required)
IP or hostname of the Proxmox host
PROXMOX_PORT
8006
API port
PROXMOX_USER
— (required)
User owning the token (e.g. root@pam)
PROXMOX_TOKEN_NAME
— (required)
API token ID
PROXMOX_TOKEN_VALUE
— (required)
API token secret (UUID)
PROXMOX_VERIFY_SSL
false
Verify the TLS certificate of the API
PROXMOX_TIMEOUT
30
HTTP timeout in seconds
SSH (optional — required by the SSH-backed tools)
The SSH-backed tools run shell commands on the Proxmox host (and, for
proxmox_vm_*, on guest VMs). They are inactive until you configure SSH.
PROXMOX_SSH_HOST defaults to PROXMOX_HOST. Prefer key auth; if both a
key and a password are set, the key is used. Guest VMs are defined
separately in vm_ssh_hosts.json.
Variable
Default
Description
PROXMOX_SSH_HOST
= PROXMOX_HOST
Host for the host-level SSH tools
PROXMOX_SSH_PORT
22
SSH port
PROXMOX_SSH_USER
root
SSH user
PROXMOX_SSH_KEY_PATH
—
Path to a private key (preferred auth)
PROXMOX_SSH_PASSWORD
—
Password auth (fallback if no key)
PROXMOX_SSH_KNOWN_HOSTS
—
Path to a known_hosts file; ignore skips host-key verification (trusted LAN only)
PROXMOX_SSH_TIMEOUT
30
SSH connect timeout in seconds
Audit log (optional)
Variable
Default
Description
PROXMOX_AUDIT_HMAC_KEY
—
If set, the SSH audit log is hash-chained with HMAC-SHA256 (tamper-evident) instead of plain SHA-256 (integrity-evident). Keep it secret and stable — changing it makes older lines fail verification. Check the chain with proxmox_audit_verify.
Security notes
The token secret sits in .env. Restrict that file to your user account
(icacls on Windows; chmod 600 on Linux).
Never expose the Proxmox API to the internet. Keep it on a trusted
LAN/VLAN, or behind a VPN.
Privilege-separate the API token. Use a non-root user where possible.
Action tools require confirm=true. Don't remove that guard.
PROXMOX_VERIFY_SSL=false is the default because homelab certs are
usually self-signed. If you've installed a trusted certificate, set it to
true.
Troubleshooting
"Authentication failed. Check PROXMOX_TOKEN_VALUE."
The token secret is wrong, or the token user is wrong. The user must match
the user the token was created under (e.g. root@pam, not just root).
"Permission denied. Token lacks privileges."
You probably have privilege separation enabled on the token but haven't
given the token a role yet. Go to Datacenter → Permissions and add an
API Token Permission for it.
"Cannot connect to :8006"
Network problem. Ping the host. Check the firewall on both ends. Confirm
the web UI loads at https://<host>:8006/ from the same machine.
"Request timed out after 30s"
Increase PROXMOX_TIMEOUT or check that the Proxmox node isn't under
heavy load.
Tools don't appear in Claude Desktop.
Check %APPDATA%\Claude\logs\mcp*.log (Windows) or
~/Library/Logs/Claude/mcp*.log (macOS) for errors. The most common cause
is a wrong path in claude_desktop_config.json or backslashes that
weren't doubled.
Project structure
proxmox-mcp/
├── proxmox_mcp/ # The MCP server package
│ ├── __main__.py # entry for `python -m proxmox_mcp`
│ ├── server.py # entry point + full tool registry (TOOLS)
│ ├── mcp_instance.py # the shared FastMCP instance
│ ├── config.py # environment-variable configuration
│ ├── http_client.py # Proxmox REST client
│ ├── ssh.py / host_ssh.py / vm_ssh.py # SSH backends (host + guests)
│ └── tools/ # one module per tool group (nodes, vms,
│ # disks, lvm, zfs, backups, ct_ops, …)
├── proxmox_mcp.py # compatibility shim (`python proxmox_mcp.py`)
├── requirements.txt # Python dependencies
├── .env.example # Template for your local .env
├── vm_ssh_hosts.json # (git-ignored) guest-VM SSH registry
├── .gitignore
├── LICENSE # GPL v3
├── README.md # This file
└── README.tr.md # Turkish version
Contributing
Issues and PRs welcome. If you add a tool, please:
Follow the existing pattern: pydantic input model + _require_config +
error handling.
Tag destructive tools with destructiveHint: True in the annotations and
require confirm=True in the input model.