proxmox-mcp
Provides tools for monitoring and managing Ceph within Proxmox VE, including health, OSDs, pools, monitors, managers, metadata servers, CephFS, and flags.
Provides tools for monitoring and managing Proxmox VE clusters: nodes, VMs and containers, storage, backups, tasks, firewall, access control, HA, SDN, Ceph, pools, replication, notifications, hardware, and raw API access.
Provides tools for monitoring and managing QEMU virtual machines through Proxmox VE, including status, configuration, power, create, clone, disks, migration, templates, cloud-init, statistics, and guest agent operations.
proxmox-mcp
Talk to your Proxmox cluster.
An open-source Model Context Protocol server for Proxmox VE. It lets Claude and other AI assistants monitor and manage your nodes, VMs, containers, storage, backups, firewall and more, all from one Docker container.
Quick start ยท Documentation ยท Tool reference ยท Contributing
"Why is the database VM so slow today?" VM 101 (db) on pve2 has averaged 94% CPU since 09:00, and pve2's IO wait has been above 30% for the same period. Its disk lives on
local-lvm, which is 91% full, and last night's backup task to the same disk is still running. Want me to show the backup task's log, or plan a migration of the VM to pve1, which has 40 GiB of free memory?
Ask about your cluster in plain English. The assistant picks from 300+ tools to look things up and, if you allow it, make changes. Some examples:
๐ฉบ "Give me a health check of the cluster."
๐ "Which VMs use the most memory, and which node has the most headroom?"
๐พ "Which guests aren't backed up, and did last night's backups succeed?"
๐งน "Find snapshots older than a month."
๐ "Review users, API tokens and permissions for anything risky."
๐ "Clone the Debian template into a new VM called web-02 with 4 GB of RAM on VLAN 20."
Highlights
๐ณ Docker-first. There's one small, distroless image (
ghcr.io/mattoddie/proxmox-mcp) forlinux/amd64andlinux/arm64. It serves Streamable HTTP for a long-running service, or stdio fordocker run -i. Each release also has plain binaries for macOS, Linux and Windows onamd64andarm64.๐ฑ๏ธ One-click Claude Desktop install. Each release has an MCP Bundle (
.mcpb) for macOS, Windows and Linux: open it and fill in a settings form. No Docker needed.๐ก๏ธ Safe by default. The server is read-only unless you turn on writes. Deleting needs a second switch, and running commands inside guests needs a third. Tools that aren't allowed aren't registered at all, destructive tools are labelled so your MCP client asks before running them, every change can be previewed with
dry_runand recorded in an audit log, and passwords and keys are redacted from output.๐งฐ Broad coverage. It covers 19 toolsets: cluster, nodes, VMs, containers, guest agent, snapshots, storage, backups, tasks, access control, firewall, HA, SDN, Ceph, pools, replication, notifications, hardware and a raw API tool.
โฑ๏ธ Task-aware. Long operations such as starts, clones, migrations and backups run as Proxmox tasks. Tools wait for them and report the result with the end of the task log, or hand back the task ID to follow up later.
๐ฏ Addressed by VMID. Ask about VM 100 and the server finds which node it's on. Single-node installs need no node names at all.
๐๏ธ Tunable. Expose only the toolsets you need, and list tools take
search,fieldsandlimit, which keeps the model's context small and focused.๐ Least privilege. Use a dedicated API token scoped with Proxmox's own roles and ACLs, so Proxmox enforces the limits too.
๐งช Tested. The test suite runs against a mock Proxmox API on every build.
Related MCP server: proxmox-mcp
Quick start
You need Docker, a Proxmox VE 8 or 9 server or cluster, and an MCP client such as Claude Code.
1. Create an API token. On any node, as root, create a read-only user and token:
pveum user add mcp@pve --comment "proxmox-mcp"
pveum acl modify / --users mcp@pve --roles PVEAuditor
pveum user token add mcp@pve mcp --privsep 0Copy the token secret from the output. You can't see it again later. Getting started explains the options, including a token that can make changes.
2. Start the server.
mkdir proxmox-mcp && cd proxmox-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/example.env -o .env
# Edit .env: set PROXMOX_URL, PROXMOX_TOKEN_ID (mcp@pve!mcp), PROXMOX_TOKEN_SECRET,
# a random MCP_AUTH_TOKEN (required; e.g. `openssl rand -hex 32`) and how to check the
# Proxmox certificate (required for https): PROXMOX_TLS_FINGERPRINT (recommended; the
# SHA-256 fingerprint from Node > System > Certificates), or PROXMOX_VERIFY_SSL=false
docker compose up -d3. Connect your assistant.
claude mcp add --transport http proxmox http://<docker-host>:8080/mcp \
--header "Authorization: Bearer <MCP_AUTH_TOKEN>"Now ask "How's my Proxmox cluster doing?" in Claude Code.
On Claude Desktop? Skip Docker: download the .mcpb bundle for your computer from the latest release, open it, and fill in the settings form. See Claude Desktop.
Using VS Code, Cursor or Codex? See Connecting MCP clients. Prefer not to run a service? Use stdio mode with docker run -i, or a release binary without Docker. On macOS or Linux: brew install mattoddie/tap/proxmox-mcp.
proxmox-mcp is listed in the MCP Registry as io.github.mattoddie/proxmox-mcp, so clients that browse the registry can install it (as the Docker image over stdio, or as a Claude Desktop bundle) and ask for the settings.
Turning on changes
Out of the box the assistant can look but not touch. To let it make changes, add these to .env and run docker compose up -d:
PROXMOX_ALLOW_WRITES=true # start/stop guests, create, clone, migrate, reconfigure, snapshot, back upโฆ
PROXMOX_ALLOW_DELETES=true # also allow deleting guests, snapshots, backups and configuration (needs writes)
PROXMOX_ALLOW_EXEC=true # also allow commands and file access inside VMs via the guest agent (needs writes)
PROXMOX_TOOLSETS=cluster,nodes,vms,containers,snapshots,backup,tasks # optional: expose fewer tools
PROXMOX_AUDIT_LOG=/audit/audit.jsonl # optional: log every change as JSON (mount ./audit; see compose.yaml)Every tool that changes something takes dry_run, so you can ask the assistant to show you a change before it makes it. The token needs matching Proxmox permissions too. Read Security before turning on writes for a production cluster.
What it can do
Toolset | What's covered |
| Cluster overview, nodes and guests at a glance, capacity and overcommit, bulk tagging and tag options, datacenter options, corosync config, metric servers, bulk guest actions |
| Node status and statistics, services, network interfaces, DNS, time, updates and repositories, subscriptions, certificates and ACME, logs, node power |
| QEMU VMs: status, configuration, power, create, clone, import from ESXi or OVA, disks, migration, templates, cloud-init, statistics |
| LXC containers: status, configuration, power, create, clone, volumes, migration, templates, interfaces, statistics |
| QEMU guest agent: OS, network and filesystem information, freeze/trim, and (with exec) commands and file access |
| VM and container snapshots: list, create, roll back, delete, and a cluster-wide view of old snapshots |
| Storage definitions and usage, volumes, ISO and template downloads, physical disks, SMART, ZFS and LVM |
| vzdump backup jobs, ad-hoc backups, backup listing, restores, pruning, guests without backups |
| Proxmox tasks: list, inspect, read logs, wait for and stop them |
| Users, groups, roles, ACLs, API tokens, realms, effective permissions, two-factor authentication |
| Rules, options, aliases, IP sets and security groups at datacenter, node and guest level, firewall log |
| High availability status, resources, groups and rules |
| SDN zones, VNets, subnets, controllers, IPAM and DNS, applying pending changes |
| Ceph health, OSDs, pools, monitors, managers, metadata servers, CephFS, flags |
| Resource pools and their members |
| Storage replication jobs, status and logs |
| Notification targets and matchers |
| PCI and USB devices, mediated devices, resource mappings, CPU models |
| An escape hatch that calls any Proxmox API path. Off unless |
See the tool reference for every tool and argument. Ready-made prompts like cluster_health_check, backup_audit and troubleshoot_guest chain the tools together for common jobs.
Documentation
The docs are also published at proxmox-mcp.mattoddie.dev/docs, with search.
๐ Getting started | Step-by-step setup, from API token to first question |
Claude Code, Claude Desktop, VS Code, Cursor, Codex, stdio mode | |
โ๏ธ Configuration | Every environment variable, Docker secrets, toolsets |
๐ณ Deployment | Compose, image tags, upgrades, TLS reverse proxy, hardening |
๐ฌ Using proxmox-mcp | Example conversations, prompts, tasks, how changes and secrets work |
๐งฐ Tool reference | Every tool and prompt, generated from the code |
๐ก๏ธ Security | Threat model, least-privilege tokens, safe write setups |
๐ก Compatibility | Supported Proxmox VE versions, Ceph, PBS, known gaps |
๐ฉน Troubleshooting | Common errors and how to fix them |
๐ ๏ธ Development | Architecture, adding a tool, testing |
On your phone? Proxly is a free Proxmox VE app for iPhone by the same author: monitor nodes, VMs and containers, start and stop guests, and take snapshots and backups without reaching for a laptop.
Contributing
Contributions are very welcome, whether that's bug reports, compatibility reports from your cluster, docs or new tools. Read the contributing guide to get started, and please follow the code of conduct. To report a vulnerability, see the security policy. Please don't open a public issue for one.
License
MIT ยฉ Matt Oddie
proxmox-mcp is an independent community project. It is not affiliated with, endorsed by or sponsored by Proxmox Server Solutions GmbH. Proxmox is a registered trademark of Proxmox Server Solutions GmbH.
Available Tools
156 toolsproxmox_check_ceph_safetyCheck if stopping/destroying a Ceph daemon is safeARead-only
Ask Ceph whether stopping or destroying an OSD, monitor or MDS is safe right now (e.g. no PGs would become unavailable). Call before proxmox_delete_ceph_osd, proxmox_delete_ceph_service or stopping services.
Inputs: id (required), action (required), service (required), node.
proxmox_check_container_featureCheck container feature supportARead-only
Check whether a container's storage supports snapshots, cloning (linked) or copying (full clone), optionally from a given snapshot, and on which nodes. Useful before proxmox_create_snapshot or proxmox_clone_container.
Inputs: vmid (required), feature (required), node, snapname.
proxmox_check_container_migrationCheck container migration preconditionsARead-only
Check whether an LXC container can be migrated, and to which nodes: reports running state, local disks/mount points that block migration, and allowed/not-allowed target nodes. Call before proxmox_migrate_container.
Inputs: vmid (required), node, target.
proxmox_check_vm_featureCheck VM feature supportARead-only
Check whether a VM's storage supports snapshots, linked clones ('clone') or full copies ('copy'), optionally for a given snapshot, and on which nodes. Useful before proxmox_clone_vm or taking snapshots.
Inputs: vmid (required), feature (required), node, snapname.
proxmox_check_vm_migrationCheck VM migration preconditionsARead-only
Check whether and where a VM can be migrated before calling proxmox_migrate_vm: allowed and blocked target nodes (with unavailable storages or blocking HA rules), local disks that would need with_local_disks/targetstorage, local devices (PCI/USB passthrough) that block migration, and mapped resources.
Inputs: vmid (required), node, target.
proxmox_get_acme_accountGet ACME accountARead-only
Get an ACME account's details: CA directory, account URL (location), status, contacts and accepted terms of service. Keys are redacted.
Inputs: name.
proxmox_get_acme_challenge_schemaGet ACME DNS plugin schemaARead-only
Show which credential fields each ACME DNS API plugin needs (e.g. CF_Token for Cloudflare), to fill data in proxmox_save_acme_plugin. Filter by api name.
Inputs: api.
proxmox_get_acme_pluginGet ACME pluginARead-only
Get one ACME challenge plugin's configuration (DNS API, nodes, validation delay). Credential values are redacted.
Inputs: id (required).
proxmox_get_api_tokenGet API tokenARead-only
Get one API token's settings (privilege separation, expiry, comment) and, when privilege-separated, its own ACL entries.
Inputs: userid (required), tokenid (required).
proxmox_get_backup_configShow config inside a backupARead-only
Show the guest configuration stored inside a backup archive (cores, memory, disks, network...) without restoring it, e.g. to check what a backup contains or which storage its disks need. Secrets are redacted.
Inputs: volid (required), raw, node.
proxmox_get_backup_jobGet backup jobARead-only
Get one backup job's settings plus the guests it currently includes and, per guest, which disks are backed up (and why others are excluded, e.g. backup=0).
Inputs: id (required), raw, include_volumes.
proxmox_get_capacity_reportGet capacity and overcommit reportARead-only
Compare what guests are allocated with the physical capacity, per node and for the cluster: vCPUs against the node's CPU threads, configured guest memory against the node's RAM, and (unless storage=false) the provisioned size of VM and container disks on each storage against its size, which shows thin-provisioning overcommit. Each figure is given for running guests and for all guests (as if every guest were started); templates are left out. A ratio above 1 means overcommitted. Read-only. The storage part lists the disk volumes on each storage, so it takes longer on big clusters.
Inputs: node, storage.
proxmox_get_ceph_configGet Ceph configurationARead-only
Read Ceph configuration: the configuration database (ceph config dump: section, name, value) and/or the ceph.conf file. Secrets such as keys are redacted.
Inputs: node, search, source.
proxmox_get_ceph_crushGet Ceph CRUSH map and rulesBRead-only
Get the decompiled CRUSH map (devices, buckets, rules) and the list of CRUSH rule names usable as a pool's crush_rule.
Inputs: node, rules_only.
proxmox_get_ceph_flagsGet Ceph OSD flagsARead-only
Show which cluster-wide Ceph OSD flags are set (noout, noscrub, nodeep-scrub, norebalance, pause...). Change them with proxmox_set_ceph_flags.
Inputs: no named parameters.
proxmox_get_ceph_logRead Ceph logBRead-only
Read lines of the Ceph cluster log (ceph.log) from a node: health changes, OSD up/down events, slow ops and scrub errors.
Inputs: node, limit, start, search.
proxmox_get_ceph_metadataGet Ceph daemon metadataARead-only
Get metadata of every Ceph daemon (mon, mgr, mds, osd) and node: host, Ceph version and release, memory. Useful to spot daemons running an outdated version after an upgrade.
Inputs: raw.
proxmox_get_ceph_osdGet Ceph OSD detailsARead-only
Get one OSD's details: daemon metadata (devices, BlueStore, memory, version) and its logical volume info (block/DB/WAL devices).
Inputs: osdid (required), node.
proxmox_get_ceph_poolGet Ceph poolARead-only
Get one Ceph pool's settings (size, min_size, PGs, autoscaler, CRUSH rule, application, protection flags) and, with statistics=true, its usage and I/O statistics.
Inputs: name (required), node, statistics.
proxmox_get_ceph_statusGet Ceph statusARead-only
Summarized Ceph cluster health: HEALTH_OK/WARN/ERR with each health check, monitor quorum, active/standby managers, OSD counts (up/in/down), PG states, raw usage and client I/O. Start here for any Ceph question; drill down with proxmox_list_ceph_osds, proxmox_list_ceph_pools or proxmox_list_ceph_services.
Inputs: raw, node.
proxmox_get_cluster_configGet cluster (corosync) configurationARead-only
Get the corosync cluster configuration: member nodes with their IDs, votes and link addresses, the totem settings, and the join information (fingerprint, addresses) used to add nodes.
Inputs: no named parameters.
proxmox_get_cluster_logGet cluster logARead-only
Read recent entries of the cluster log (task starts/ends, logins and other cluster events from all nodes).
Inputs: max, search.
proxmox_get_cluster_optionsGet datacenter optionsARead-only
Get datacenter-wide options (datacenter.cfg): keyboard, console, migration network/type, HA shutdown policy, bandwidth limits, MAC prefix, tag style, next-id range and more.
Inputs: no named parameters.
proxmox_get_cluster_statusGet cluster overviewARead-only
One-call overview of the whole cluster: name, quorum, Proxmox version, every node (online state, CPU, memory, uptime), guest counts by state, totals, storage usage and HA state. A good first call.
Inputs: no named parameters.
proxmox_get_containerGet container detailsARead-only
Get an LXC container's live status (CPU, memory, swap, rootfs usage, uptime) together with a summary of its configuration: hostname, OS, cores, memory, swap, rootfs and mount points, network interfaces with configured IPs, live IP addresses (when running), features, unprivileged, onboot, tags and pending changes that apply on next restart. Use proxmox_get_container_config for the full raw config.
Inputs: vmid (required), node.
proxmox_get_container_configGet container configurationARead-only
Get an LXC container's full configuration as stored by Proxmox (secrets redacted). Options: current=true for the running values instead of pending ones, snapshot to read the config as saved in a snapshot, or pending=true to list each key with its current and pending value. The returned digest can be passed to proxmox_update_container_config for optimistic locking.
Inputs: vmid (required), node, current, pending, +1 more.
proxmox_get_container_interfacesGet container IP addressesARead-only
Get the live network interfaces and IP addresses (IPv4 and IPv6) inside a running LXC container, including addresses obtained via DHCP/SLAAC that the config doesn't show. The container must be running.
Inputs: vmid (required), raw, node.
proxmox_get_container_statsGet container performance historyARead-only
Summarize an LXC container's performance history from RRD data: average, maximum and latest CPU %, memory, swap, disk usage, network and disk I/O rates over the chosen timeframe. Set points=true to also get the individual data points.
Inputs: vmid (required), cf, node, points, +1 more.
proxmox_get_custom_cpu_modelGet a custom CPU modelARead-only
Get one custom CPU model definition, including its digest.
Inputs: name (required).
proxmox_get_disk_smartGet disk SMART dataARead-only
Get a disk's SMART health and attributes (ATA attribute table, or the text report for NVMe/SAS).
Inputs: disk (required), raw, node, health_only.
proxmox_get_firewall_logRead the firewall logARead-only
Read the firewall log of a node (all its traffic, including guests on it) or of one guest. Only packets matching rules/policies with a log level other than nolog are logged; set log_level_in on the options or log on a rule to see drops.
Inputs: node, vmid, limit, scope, +4 more.
proxmox_get_firewall_optionsGet firewall optionsARead-only
Get firewall options for the datacenter (enable, default policies, ebtables, log rate limit), a node (enable, nftables, conntrack, synflood/smurf/tcpflags protection, log levels) or a guest (enable, policies, MAC/IP filter, DHCP, NDP, RA, log levels). effective fills in Proxmox's defaults for unset options.
Inputs: node, vmid, scope.
proxmox_get_firewall_ruleGet a firewall ruleARead-only
Get one firewall rule by position at any level (cluster, node, guest or security group), with its digest for safe updates.
Inputs: pos (required), node, vmid, group, +1 more.
proxmox_get_groupGet groupBRead-only
Get a group's members and comment.
Inputs: groupid (required).
proxmox_get_guest_filesystemsGet guest filesystems (agent)ARead-only
List a running VM's mounted filesystems from inside the guest (QEMU guest agent get-fsinfo): mountpoint, type, used/total space and backing disks. Use it to check real disk usage inside a VM (Proxmox's own disk figures for VMs are not filesystem usage). VMs only.
Inputs: vmid (required), raw, node.
proxmox_get_guest_firewall_statusGet a guest's firewall statusARead-only
Whole-picture firewall view for one VM/container, for questions like 'why can't I reach VM X': whether the firewall is enabled at datacenter, node and guest level and on each NIC (firewall=1), the effective policies, the guest's rules (one line each), IP/MAC filters, and plain-language findings about what is blocking or not filtering traffic.
Inputs: vmid (required), node.
proxmox_get_guest_infoGet guest OS info (agent)ARead-only
Ask a running VM's QEMU guest agent about the guest: OS name/version/kernel, hostname, timezone, guest clock (and its skew from this server), vCPUs online and the agent version with its disabled commands. VMs only (containers need no agent). Individual queries that fail are reported under errors instead of failing the call. Use proxmox_get_guest_network for IP addresses.
Inputs: vmid (required), raw, node.
proxmox_get_guest_memory_blocksGet guest memory blocks (agent)ARead-only
Show a running VM's memory blocks as the guest sees them (QEMU guest agent get-memory-blocks/get-memory-block-info): block size and how many blocks/how much memory is online. Useful after memory hotplug. VMs only; not all guest OSes support it.
Inputs: vmid (required), node.
proxmox_get_guest_networkGet guest network interfaces (agent)ARead-only
List a running VM's network interfaces as seen inside the guest (via the QEMU guest agent): name, MAC, IPv4/IPv6 addresses with prefix, and traffic counters. The reliable way to find a VM's IP address. Loopback is hidden unless include_loopback=true. VMs only; for containers use proxmox_get_container_interfaces.
Inputs: vmid (required), raw, node, include_loopback.
proxmox_get_guest_usersGet logged-in guest users (agent)ARead-only
List the users currently logged in to a running VM (QEMU guest agent get-users), with domain and login time. VMs only.
Inputs: vmid (required), node.
proxmox_get_ha_groupGet an HA groupARead-only
Get one HA group's configuration (PVE 8; deprecated in PVE 9 in favour of HA rules).
Inputs: group (required).
proxmox_get_ha_resourceGet an HA resourceARead-only
Get one HA resource's configuration, its current status, and the HA rules that reference it (PVE 9+).
Inputs: sid (required).
proxmox_get_ha_ruleGet an HA ruleARead-only
Get one HA rule (PVE 9+) with its digest.
Inputs: rule (required).
proxmox_get_ha_statusGet HA statusARead-only
High-availability overview: quorum, the current CRM master, each node's LRM state (active/idle/maintenance, last update), fencing/arming state (PVE 9.1+), and every HA-managed service with its node and state. Use proxmox_list_ha_resources for the configured settings.
Inputs: raw.
proxmox_get_import_metadataGet guest import metadataARead-only
Read what Proxmox recognises in an importable guest: a VM on an ESXi storage (volume like "esxi1:ha-datacenter/datastore1/web01/web01.vmx") or an OVA/OVF appliance on a storage with import content ("local:import/appliance.ova"). Find them with proxmox_list_storage_content content=import. Returns the source type, the parameters Proxmox suggests for creating the VM (create_args), the disks and NICs found and warnings about anything that won't carry over (a running source VM, lost EFI state, an OVA that has to be extracted first). Nothing is changed; create the VM with proxmox_import_vm. Proxmox VE 8.2+ (OVA/OVF 8.3+).
Inputs: volume (required), node, storage.
proxmox_get_next_vmidGet next free VMIDARead-only
Get the next free VM/container ID, or check whether a specific ID is free.
Inputs: vmid.
proxmox_get_node_capabilitiesGet node QEMU capabilitiesARead-only
Get what a node's QEMU supports for VM configuration: CPU models (built-in and custom), machine types/versions (q35, i440fx) and the VM-specific CPU flags that can be toggled. Use it to pick valid values for a VM's cpu/machine options.
Inputs: arch, node, sections.
proxmox_get_node_certificatesGet node certificatesARead-only
List the TLS certificates of a node's web interface/API (pve-root-ca, pve-ssl and any custom or ACME pveproxy-ssl certificate) with subject, issuer, SANs, validity, days left and fingerprint. Private keys are never returned.
Inputs: node.
proxmox_get_node_configGet node optionsARead-only
Get a node's own options (/etc/pve/nodes//config): notes/description, wake-on-LAN MAC, ACME account and domains, start-on-boot delay, ballooning target and location, plus the digest for safe updates.
Inputs: node.
proxmox_get_node_dnsGet node DNS settingsARead-only
Get a node's DNS resolver settings: search domain and up to three name servers.
Inputs: node.
proxmox_get_node_hostsGet node /etc/hostsARead-only
Read a node's /etc/hosts file and its digest (pass the digest to proxmox_set_node_hosts to avoid overwriting concurrent edits).
Inputs: node.
proxmox_get_node_journalRead node systemd journalCRead-only
Read a node's systemd journal: the last N entries (default 100) or a time range, optionally only one unit, a syslog identifier, a priority level or kernel messages.
Inputs: node, unit, since, until, +5 more.
proxmox_get_node_netstatGet guest network countersARead-only
Traffic counters of the guests' tap/veth network devices on a node (bytes in/out per device and VMID), as seen from the host.
Inputs: node, vmid.
proxmox_get_node_network_interfaceGet a node network interfaceARead-only
Get the configuration of one network interface on a node (as stored in /etc/network/interfaces, including pending changes).
Inputs: iface (required), raw, node.
proxmox_get_node_package_versionsGet Proxmox package versionsARead-only
List the installed versions of the important Proxmox packages on a node (like pveversion -v), including the running kernel.
Inputs: node, search.
proxmox_get_node_reportGet node system reportARead-only
The node's pvereport: a long text dump of versions, hardware, storage, network, cluster and guest configuration, as used for support requests. Large; truncated to max_chars. Can take a while to generate.
Inputs: node, max_chars.
proxmox_get_node_statsGet node performance historyARead-only
Node performance history from the RRD database (CPU, IO wait, load, memory, swap, root disk, network, ARC...) over a timeframe, summarized as min/avg/max/last per metric plus a short downsampled series. Network values are bytes per second.
Inputs: cf, raw, node, points, +2 more.
proxmox_get_node_statusGet node statusARead-only
Detailed status of one node: CPU model/sockets/cores and usage, IO wait, load average, memory/swap/root filesystem usage, kernel, Proxmox VE version, boot mode (EFI/BIOS, secure boot), uptime, KSM sharing and the subscription status. Use proxmox_list_nodes for all nodes at a glance and proxmox_get_node_stats for history.
Inputs: raw, node.
proxmox_get_node_subscriptionGet node subscriptionARead-only
Get a node's subscription status, level, product, sockets and next due date. The key itself is never shown.
Inputs: node.
proxmox_get_node_syslogRead node syslogARead-only
Read a node's system log (journal rendered as syslog lines), optionally for one service and a time range. Page with start/limit. For the raw systemd journal with 'last N lines' semantics use proxmox_get_node_journal.
Inputs: node, limit, since, start, +3 more.
proxmox_get_node_timeGet node time and time zoneARead-only
Get a node's current time (UTC), local time and configured time zone. Useful for spotting clock drift between nodes.
Inputs: node.
proxmox_get_notification_endpointGet notification endpointARead-only
Get one notification endpoint's configuration. The type is looked up when omitted. Tokens, passwords and webhook secrets are redacted; webhook headers and body are shown decoded (credential-like headers redacted).
Inputs: name (required), raw, type.
proxmox_get_notification_matcherGet notification matcherARead-only
Get one notification matcher's rules and targets (plus its digest for safe updates).
Inputs: name (required).
proxmox_get_notification_matcher_fieldsGet notification matcher fieldsARead-only
List the metadata fields notifications carry (type, hostname, job-id...) and their known values, for writing match_field rules in proxmox_save_notification_matcher.
Inputs: no named parameters.
proxmox_get_package_changelogGet package changelogARead-only
Get the changelog of a package available on a node, e.g. to see what an update to pve-manager or proxmox-kernel changes. Truncated to max_chars.
Inputs: package (required), node, version, max_chars.
proxmox_get_permissionsGet effective permissionsARead-only
Show effective privileges per path for the API token/user this server uses (default) or for another user or token. The first thing to check when a tool fails with 403 / 'Permission check failed': it shows exactly which privileges are held where. Use path to check a single path such as /vms/100.
Inputs: path, userid.
proxmox_get_poolGet resource poolARead-only
Get a resource pool's comment and members: guests (status, node, CPU/memory use) and storage (usage).
Inputs: poolid (required), raw, type.
proxmox_get_realmGet realmBRead-only
Get an authentication realm's configuration (servers, base DN, sync options, OpenID issuer...). Bind passwords and client keys are redacted.
Inputs: realm (required).
proxmox_get_replication_jobGet replication jobARead-only
Get one replication job's configuration (with digest for safe updates) and its current status on the source node.
Inputs: id (required), node.
proxmox_get_replication_logGet replication logARead-only
Read the log of a replication job's last run from the source node, e.g. to diagnose a failing job.
Inputs: id (required), node, limit, start.
proxmox_get_resource_mappingGet a resource mappingARead-only
Get one PCI, USB or directory resource mapping with its per-node entries and digest.
Inputs: id (required), kind (required).
proxmox_get_roleGet roleBRead-only
Get the privileges of one role, grouped by area (VM, Datastore, Sys...).
Inputs: roleid (required).
proxmox_get_sdn_ipam_statusList IPAM entriesARead-only
List the IP allocations recorded in an SDN IPAM (default the built-in 'pve' IPAM): IP, MAC, hostname, VMID, vnet/subnet and gateway entries. Use it to find which guest holds an address or which IPs are free. Related: proxmox_save_sdn_vnet_ip to add or change a mapping.
Inputs: ipam, vmid, vnet, limit, +1 more.
proxmox_get_sdn_objectGet an SDN objectARead-only
Get the full configuration of one SDN zone, vnet, subnet, controller, IPAM or DNS plugin, including its digest for optimistic locking. With pending=true, uncommitted changes are shown under pending.
Inputs: id (required), kind (required), vnet, pending, +1 more.
proxmox_get_sdn_pending_diffPreview SDN apply (dry run)ARead-only
Dry-run proxmox_apply_sdn for one node: shows the diff between the running and the pending network interfaces (/etc/network/interfaces.d/sdn) and FRR routing configuration. Use it to review staged SDN changes before applying them.
Inputs: node.
proxmox_get_sdn_statusGet SDN status on nodesARead-only
Show the live SDN state on nodes: each zone's status (available/pending/error) per node and the status of the vnets in it. Use it after proxmox_apply_sdn to confirm the configuration came up, or to find nodes where a zone is in error.
Inputs: node, zone, vnets.
proxmox_get_snapshotGet snapshot detailsARead-only
Get a snapshot of a VM or container: its description, time, parent, whether RAM was saved, and the guest configuration as it was at that snapshot (disks and networks summarized, secrets redacted). Useful to see what a rollback would restore.
Inputs: vmid (required), snapname (required), raw, node.
proxmox_get_storageGet storageARead-only
Get one storage definition (full config, secrets redacted) and its status/usage on each node. Pass node for that node's detailed status (active, enabled, available bytes).
Inputs: storage (required), node.
proxmox_get_storage_statsGet storage usage historyARead-only
Summarize a storage's usage over time from its RRD data (current, min, max, growth over the period) with a few sample points. Useful for capacity planning.
Inputs: storage (required), cf, node, samples, +1 more.
proxmox_get_taskGet task statusARead-only
Get a task's status (running/stopped), exit status and the last lines of its log.
Inputs: upid (required), log_lines.
proxmox_get_task_logRead task logARead-only
Read a task's log, paging from the start (or the end with tail=true).
Inputs: upid (required), tail, limit, start.
proxmox_get_userGet userARead-only
Get one user's configuration: enabled state, expiry, name, email, groups, comment, API tokens and TFA entries. For effective permissions use proxmox_get_permissions.
Inputs: userid (required).
proxmox_get_versionGet Proxmox VE versionARead-only
Get the Proxmox VE version and release of the API endpoint this server talks to.
Inputs: no named parameters.
proxmox_get_vmGet VM detailsARead-only
Get a VM's live status (run state, CPU, memory, disk/network I/O, uptime, HA, lock, guest agent, QEMU version) together with a summary of its configuration (CPU, memory, disks, NICs, boot order, firmware, cloud-init, tags, notes) and any pending changes that need a restart. Use proxmox_get_vm_config for the raw config.
Inputs: vmid (required), raw, node.
proxmox_get_vm_cloudinitGet VM cloud-init dataARead-only
Show a VM's cloud-init settings with current vs pending values (pending ones need proxmox_regenerate_vm_cloudinit or a restart to reach the guest), plus the generated user-data, network-config and meta-data as the guest will see them. Passwords are redacted.
Inputs: vmid (required), dump, node.
proxmox_get_vm_configGet VM configurationARead-only
Get a VM's configuration as Proxmox stores it (key โ value, secrets redacted). By default pending changes are shown applied; current=true shows the running values instead, pending=true lists every key with its current and pending value, and snapshot reads the config saved in a snapshot. The digest can be passed to proxmox_update_vm_config for safe concurrent edits.
Inputs: vmid (required), node, current, pending, +1 more.
proxmox_get_vm_statsGet VM performance historyARead-only
Get a VM's performance history from Proxmox's RRD database: min/avg/max of CPU %, memory, network and disk throughput and pressure stalls over the last hour/day/week/month/year, plus a downsampled time series. Use for 'was it busy?', trend and capacity questions.
Inputs: vmid (required), cf, raw, node, +2 more.
proxmox_get_volumeGet volume attributesBRead-only
Get a volume's attributes: path on disk, format, size, used space, notes and protection flag.
Inputs: volume (required), node, storage.
proxmox_get_vzdump_defaultsGet backup defaultsARead-only
Show the vzdump defaults a node applies to backups (from /etc/vzdump.conf, merged with a storage's settings when storage is given): default storage, mode, compression, retention, bandwidth limits and so on.
Inputs: node, storage.
proxmox_get_zfs_poolGet ZFS pool statusARead-only
Get a zpool's detailed status (like zpool status): state, status/action messages, last scrub/resilver, errors and the vdev tree with read/write/checksum error counters.
Inputs: name (required), node.
proxmox_list_aclList ACL entriesARead-only
List access control entries: which role a user, group or API token has on which path (/, /vms/100, /storage/local, /pool/x, /nodes/pve1...) and whether it propagates to sub-paths. Filters combine. For what a user can effectively do, use proxmox_get_permissions.
Inputs: path, role, type, user, +4 more.
proxmox_list_acme_accountsList ACME accountsBRead-only
List the cluster's registered ACME accounts (used to order node certificates), with their CA directory and contacts.
Inputs: fields, search.
proxmox_list_acme_directoriesList ACME directoriesARead-only
List the known ACME CA directories (Let's Encrypt production/staging...). With directory, also fetch that CA's metadata: terms-of-service URL (needed to register an account) and whether external account binding is required. Fetching directory makes the node connect to that URL, so it needs write access.
Inputs: fields, search, directory.
proxmox_list_acme_pluginsList ACME challenge pluginsBRead-only
List the cluster's ACME challenge plugins (standalone HTTP and DNS API plugins). Credentials in plugin data are redacted; only their keys are shown.
Inputs: type, fields, search.
proxmox_list_all_snapshotsList snapshots across all guestsARead-only
List snapshots of every VM and container in the cluster (or a filtered set), oldest first, with guest, node, time, age in days and description. Use older_than_days to find stale snapshots that hold back storage space and slow down disks. Guests whose snapshots can't be read are reported under errors.
Inputs: node, type, limit, vmids, +3 more.
proxmox_list_api_tokensList API tokensARead-only
List API tokens (full ID user@realm!name, privilege separation, expiry, comment) for one user, or for all users when userid is omitted. Secrets can never be read back.
Inputs: fields, search, userid.
proxmox_list_appliance_templatesList appliance templatesARead-only
List the LXC container templates available for download from the Proxmox appliance index (Debian, Ubuntu, Alpine..., and TurnKey apps). Download one with proxmox_download_appliance_template. If the list is empty, the node may need pveam update.
Inputs: node, limit, fields, search, +1 more.
proxmox_list_backup_filesBrowse files in a PBS backupARead-only
Browse the files inside a Proxmox Backup Server backup (single-file restore): start at path "/" to see the archives (disk images/filesystem archives), then drill into directories. Only works for PBS storages. Opening VM disk images starts a temporary restore VM on the node and can take a while on first access.
Inputs: volid (required), storage (required), node, path, +3 more.
proxmox_list_backup_jobsList backup jobsARead-only
List the cluster's scheduled backup (vzdump) jobs: schedule, next run, enabled, target storage, mode, which guests (all/VMID list/pool, exclusions), compression and retention. See proxmox_get_backup_job for one job with the guests and disks it covers, and proxmox_list_unbacked_guests for guests no job covers.
Inputs: raw, fields, search.
proxmox_list_backupsList backupsARead-only
List backup archives across every storage that holds backups (local dirs, NFS/CIFS, Proxmox Backup Server...), newest first: volume ID, guest, time, size, format, notes, protection and PBS verification state. Filter by vmid, type, storage, node or age. Shared storages are listed once. Use the volid with proxmox_restore_backup, proxmox_get_backup_config, proxmox_update_backup or proxmox_delete_backup.
Inputs: raw, node, type, vmid, +6 more.
proxmox_list_ceph_fsList CephFS file systemsARead-only
List CephFS file systems with their metadata and data pools. MDS daemons serving them are listed by proxmox_list_ceph_services.
Inputs: node, fields, search.
proxmox_list_ceph_osdsList Ceph OSDsARead-only
List Ceph OSDs from the OSD tree: host, up/down, in/out, device class, usage, PGs, CRUSH weight, latency and version, plus the per-host grouping and cluster-wide OSD flags (noout etc.). Filter by host, status or device class.
Inputs: raw, host, node, limit, +4 more.
proxmox_list_ceph_poolsList Ceph poolsARead-only
List Ceph pools with replication (size/min_size), PG count and autoscale mode (with the autoscaler's optimal PG count), application, CRUSH rule and usage %. Related: proxmox_get_ceph_pool, proxmox_update_ceph_pool.
Inputs: raw, node, fields, search.
proxmox_list_ceph_servicesList Ceph monitors, managers and metadata serversARead-only
List Ceph daemons of one type or all: monitors (quorum, rank), managers (active/standby) and metadata servers (MDS state, CephFS, rank), with host, address and version.
Inputs: node, type.
proxmox_list_containersList containersARead-only
List LXC containers across the cluster with status, node, CPU, memory, disk, uptime, tags and pool. For VMs and containers together use proxmox_list_guests.
Inputs: raw, node, limit, fields, +3 more.
proxmox_list_custom_cpu_modelsList custom CPU modelsARead-only
List cluster-wide custom CPU models (base model plus flag changes). VMs use them as cpu: custom-. Related: proxmox_get_node_capabilities for built-in models and flags.
Inputs: raw, fields, search.
proxmox_list_directory_mountsList directory mountsBRead-only
List the directory storages Proxmox manages on a node's disks (filesystems mounted under /mnt/pve/ via systemd mount units).
Inputs: node, fields, search.
proxmox_list_disksList physical disksARead-only
List a node's physical disks with device path, model, serial, size, type (ssd/hdd/nvme/usb), SMART health, wearout and what uses them (LVM, ZFS, Ceph OSD, partitions, mounted). Use type=unused to find disks free for new storage.
Inputs: raw, node, type, fields, +3 more.
proxmox_list_firewall_aliasesList firewall aliasesARead-only
List IP/network aliases defined at datacenter (cluster) or guest level. Aliases are named addresses usable in rule source/dest.
Inputs: node, vmid, scope, fields, +1 more.
proxmox_list_firewall_groupsList firewall security groupsARead-only
List the datacenter's security groups (reusable rule sets) with their comment and rule count. See a group's rules with proxmox_list_firewall_rules scope=group; apply a group to a guest/node with a rule of type group.
Inputs: fields, search.
proxmox_list_firewall_ipsetsList firewall IP setsARead-only
List IP sets at datacenter (cluster) or guest level with their entries (CIDRs, nomatch exclusions, comments). Reference them in rules as +name (or +dc/name, +guest/name). Special sets: 'management' (hosts allowed to reach the web UI/SSH when the firewall is on), 'blacklist', and per-NIC 'ipfilter-netX' on guests.
Inputs: name, node, vmid, scope, +2 more.
proxmox_list_firewall_macrosList firewall macrosBRead-only
List the predefined firewall macros (SSH, HTTP, DNS, Ceph, ...) usable as a rule's macro instead of proto/port.
Inputs: fields, search.
proxmox_list_firewall_refsList firewall alias/IP set referencesARead-only
List the aliases and IP sets that can be used in rule source/dest at datacenter (cluster) or guest level, with the exact reference string to use (e.g. +dc/management, dc/myalias).
Inputs: node, type, vmid, scope, +2 more.
proxmox_list_firewall_rulesList firewall rulesARead-only
List the firewall rules of the datacenter (cluster), a node, a VM/container (guest) or a security group, in evaluation order (pos 0 first). Each rule has a readable one-line form like 'IN SSH(ACCEPT) -i net0 -source +mgmt # admins'. Rules of type group pull in a security group's rules. For 'why can't I reach VM X' start with proxmox_get_guest_firewall_status.
Inputs: raw, node, vmid, group, +3 more.
proxmox_list_groupsList groupsBRead-only
List user groups with their members and comments.
Inputs: fields, search.
proxmox_list_guestsList VMs and containersARead-only
List virtual machines and containers across the cluster with status, node, CPU, memory, disk, uptime, tags and pool. Filter by type, node, status, tag, pool or a search string, and sort by resource use.
Inputs: raw, tag, node, pool, +7 more.
proxmox_list_ha_groupsList HA groupsARead-only
List HA groups (node lists with priorities, restricted, nofailback). Deprecated in PVE 9, where groups are migrated to node-affinity rules (proxmox_list_ha_rules).
Inputs: fields, search.
proxmox_list_ha_resourcesList HA resourcesBRead-only
List HA-managed VMs and containers with their requested state, group, restart/relocate limits, failback, comment, guest name and current status (node and CRM state).
Inputs: type, limit, fields, search.
proxmox_list_ha_rulesList HA rulesBRead-only
List HA rules (PVE 9+): node-affinity rules (which nodes resources prefer or must run on, with priorities) and resource-affinity rules (keep resources together or apart).
Inputs: type, fields, search, resource.
proxmox_list_lvmList LVM volume groupsBRead-only
List a node's LVM volume groups with size, free space and physical volumes.
Inputs: node, fields, search.
proxmox_list_lvm_thinList LVM thin poolsARead-only
List a node's LVM thin pools with data and metadata usage. Thin pools that run out of metadata space fail badly, so watch metadata_usage.
Inputs: node, fields, search.
proxmox_list_metric_serversList metric serversBRead-only
List external metric servers (InfluxDB, Graphite, OpenTelemetry) that Proxmox sends performance data to.
Inputs: fields, search.
proxmox_list_node_mdev_typesList mediated device typesARead-only
List the mediated device (mdev, e.g. NVIDIA vGPU / Intel GVT-g) types a PCI device offers, with how many instances are still available. Use a device with mdev support from proxmox_list_node_pci_devices.
Inputs: pci_id (required), node, fields, search.
proxmox_list_node_networkList node network interfacesARead-only
List a node's network configuration: physical NICs, Linux bridges, bonds, VLANs and OVS objects with addresses, gateways, ports and comments. Interfaces that are configured but not active are flagged; that usually means pending (unapplied) changes from proxmox_save_node_network_interface, or a down link. Apply with proxmox_apply_node_network or discard with proxmox_revert_node_network.
Inputs: raw, node, type, fields, +1 more.
proxmox_list_node_pci_devicesList PCI devicesARead-only
List a node's PCI devices for passthrough planning: address, class, vendor/device names and IDs, IOMMU group (with the other devices in the same group, which must be passed through together) and whether it supports mediated devices (vGPU). Memory controllers, bridges and processors are hidden unless all=true. IOMMU group -1 means IOMMU is off.
Inputs: all, raw, node, class, +4 more.
proxmox_list_node_repositoriesList APT repositoriesARead-only
List a node's APT repositories by file with enabled/disabled state, URIs, suites and components, any parse errors and warnings (e.g. enterprise repo without subscription, mixed suites), and which standard Proxmox repositories are configured. Use path/index and the digest with proxmox_set_node_repository.
Inputs: raw, node.
proxmox_list_nodesList nodesBRead-only
List the cluster's nodes with online state, CPU and memory usage, uptime and subscription level.
Inputs: raw, fields, search.
proxmox_list_node_servicesList node servicesARead-only
List the Proxmox-related system services on a node (pveproxy, pvedaemon, corosync, pve-cluster, chrony, sshd, postfix...) with their running state and whether they are enabled. Failed services are listed first.
Inputs: node, fields, search.
proxmox_list_node_updatesList available package updatesARead-only
List the package updates available on a node (from the last package index refresh) with installed and new versions, origin and priority, plus counts. Run proxmox_refresh_node_updates first for fresh results. Installing updates is not available through the API.
Inputs: node, limit, fields, search.
proxmox_list_node_usb_devicesList USB devicesARead-only
List a node's USB devices for passthrough: vendor:product ID, manufacturer and product names, bus/port path, speed and serial. Pass a device to a VM by ID (host=vendor:product) or port (host=bus-port), or via a USB resource mapping.
Inputs: node, fields, search.
proxmox_list_notification_matchersList notification matchersCRead-only
List notification matchers: rules that route notifications (by severity, metadata fields such as type/hostname/job-id, and calendar time) to targets.
Inputs: fields, search.
proxmox_list_notification_targetsList notification targetsARead-only
List all notification targets (endpoints of every type: sendmail, smtp, gotify, webhook) with type, disabled state, origin and comment. details=true adds each endpoint's configuration (secrets redacted). Matchers decide which notifications go to which target; see proxmox_list_notification_matchers.
Inputs: fields, search, details.
proxmox_list_poolsList resource poolsARead-only
List resource pools (groups of VMs, containers and storage used for permissions and organisation) with their comments and member counts. Not ZFS or Ceph pools; see proxmox_get_pool for members.
Inputs: fields, search.
proxmox_list_privilegesList privilegesARead-only
List every privilege Proxmox knows (derived from the built-in Administrator role, which holds them all), grouped by area. Use when building a custom role with proxmox_save_role.
Inputs: no named parameters.
proxmox_list_realmsList realmsBRead-only
List authentication realms (pam, pve, LDAP, Active Directory, OpenID Connect) with type, TFA provider and comment.
Inputs: fields, search.
proxmox_list_realm_sync_jobsList realm sync jobsBRead-only
List scheduled realm sync jobs (periodic LDAP/AD/OpenID user and group sync) with schedule, last and next run.
Inputs: fields, search.
proxmox_list_replication_jobsList replication jobsARead-only
List storage replication jobs (ZFS-based guest replication to another node) with guest, target, schedule, rate limit and live status from the source node: last/next sync, duration, failure count and last error.
Inputs: raw, guest, fields, search, +1 more.
proxmox_list_resource_mappingsList resource mappingsARead-only
List cluster resource mappings of one kind: PCI or USB devices, or directories (for virtiofs), each mapping a logical name to the device/path on every node. VMs reference them as e.g. hostpci0: mapping=, which allows migration. With check_node, Proxmox validates the entries for that node.
Inputs: kind (required), fields, search, check_node.
proxmox_list_resourcesList cluster resourcesARead-only
List cluster resources of any kind from /cluster/resources: nodes, guests, storage, pools and SDN zones. Use proxmox_list_guests for a friendlier guest list.
Inputs: type, limit, fields, search.
proxmox_list_rolesList rolesARead-only
List roles with their privileges. Built-in roles (Administrator, PVEAdmin, PVEVMAdmin, PVEAuditor, NoAccess...) are flagged builtin=true and cannot be changed. Use privileges=false for names only.
Inputs: fields, search, builtin, privileges.
proxmox_list_sdn_fabricsList SDN fabricsARead-only
List SDN fabrics (PVE 9 underlay networks: OpenFabric, OSPF, WireGuard, BGP) with their nodes. Give node and fabric to also read that node's live fabric routes, neighbors and interfaces. Read-only; fabrics are edited in the web UI or with proxmox_api_request.
Inputs: node, fabric, pending, running.
proxmox_list_sdn_objectsList SDN objectsARead-only
List Software-Defined Networking objects of one kind: zones, vnets, subnets of a vnet, controllers, IPAMs or DNS plugins. Use pending=true to see uncommitted changes (state new/changed/deleted). Related: proxmox_get_sdn_object for one object, proxmox_get_sdn_status for the live state on nodes.
Inputs: kind (required), raw, type, vnet, +5 more.
proxmox_list_sdn_route_policiesList SDN prefix lists and route mapsARead-only
List SDN routing policy objects (PVE 9): prefix lists with their entries, and route maps with their entries (match/set clauses). Read-only. These are referenced by controllers (route-map-in/out) and fabrics (route_filter).
Inputs: pending, running.
proxmox_list_snapshotsList snapshots of a guestARead-only
List the snapshots of a VM or container (the type is detected from the VMID): name, parent, description, creation time, age, whether RAM state was saved (VMs), and which snapshot the guest currently runs from, plus an indented tree view. For stale snapshots across all guests use proxmox_list_all_snapshots.
Inputs: vmid (required), raw, node, fields, +1 more.
proxmox_list_storageList storageARead-only
List the datacenter's storage definitions (local dirs, LVM, ZFS, NFS, CIFS, PBS, Ceph...) with type, allowed content, shared/enabled flags, node restriction, server/path/pool details and backup retention, merged with each node's live status and usage. Use proxmox_list_storage_content to see what's on one.
Inputs: raw, node, type, fields, +2 more.
proxmox_list_storage_contentList storage contentARead-only
List the volumes on a storage: ISO images, container templates, backups, VM/CT disks, snippets and import files, with format, size, owner VMID, creation time, notes and protection. Filter by content type or VMID (e.g. all backups of guest 100).
Inputs: storage (required), raw, node, vmid, +4 more.
proxmox_list_tasksList tasksARead-only
List Proxmox tasks (backups, migrations, starts, clones...). Without node, lists recent tasks across the whole cluster; with node, reads that node's task history with server-side filters. Use errors=true to find failures.
Inputs: node, type, user, vmid, +6 more.
proxmox_list_tfaList TFA entriesARead-only
List users' second factors (TOTP, WebAuthn, recovery keys, Yubico) with type, description, creation time and enabled state, plus TFA lock-outs. No secrets are returned. Unlock a locked-out user with proxmox_unlock_tfa.
Inputs: fields, search, userid.
proxmox_list_unbacked_guestsList guests without backup jobARead-only
List VMs and containers that no backup job covers, with node and status. Use it to audit backup coverage; add them with proxmox_save_backup_job or back them up once with proxmox_backup_guests.
Inputs: fields, search.
proxmox_list_usersList usersARead-only
List Proxmox users with enabled state, expiry, realm, name, email, groups, API token count and TFA lock-out state. Use proxmox_get_user for one user's details and tokens.
Inputs: raw, group, limit, realm, +3 more.
proxmox_list_vmsList VMs with live detailsARead-only
List QEMU VMs straight from the nodes (GET /nodes/{node}/qemu?full=1), with details proxmox_list_guests lacks: disk I/O counters, host memory, PSI pressure stalls and the running QEMU version/machine. Without node, queries every online node. For a quick cluster-wide list with filters by tag/pool use proxmox_list_guests instead.
Inputs: raw, node, limit, fields, +2 more.
proxmox_list_zfs_poolsList ZFS poolsARead-only
List a node's ZFS pools (zpools) with size, allocation, fragmentation, dedup ratio and health. Use proxmox_get_zfs_pool for the vdev tree and scrub status.
Inputs: node, fields, search.
proxmox_preview_backup_prunePreview backup pruningARead-only
Dry run of pruning a backup storage: shows which backups the retention rules (the storage's own, or retention) would keep and which they would remove. Nothing is deleted; run proxmox_prune_backups with the same arguments to apply.
Inputs: storage (required), node, type, vmid, +1 more.
proxmox_scan_storageScan for storageARead-only
Discover storage that can be added with proxmox_save_storage: NFS exports or CIFS shares on a server, PBS datastores, iSCSI targets on a portal, or local LVM volume groups, LVM thin pools and ZFS pools on a node. The nfs, cifs, pbs and iscsi scans make the node contact the given server, possibly with credentials, so they need write access (PROXMOX_ALLOW_WRITES=true); the local scans are always available.
Inputs: type (required), vg, node, port, +6 more.
proxmox_simulate_scheduleSimulate a job scheduleARead-only
Show the next run times of a Proxmox calendar-event schedule (as used by backup, replication and other jobs), e.g. 'mon..fri 02:00' or '*/15'. Useful to check a schedule before saving it.
Inputs: schedule (required), starttime, iterations.
proxmox_wait_for_taskWait for a taskARead-only
Wait until a running task finishes (or the timeout passes) and return its outcome and log tail.
Inputs: upid (required), timeout_s.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 156 tools
There is real surface overlap โ list_guests vs list_vms vs list_containers vs list_resources, get_node_syslog vs get_node_journal, list_snapshots vs list_all_snapshots, node_status vs node_stats vs cluster_status vs capacity_report โ but nearly every description explicitly states when to prefer a sibling tool (e.g. 'For VMs and containers together use proxmox_list_guests'). With 156 tools the sheer number of near-neighbours means a few misselections are likely, but boundaries are documented rather than blurred.
Every tool follows the same proxmox_<verb>_<noun> pattern with a small, predictable verb set (get, list, check, save, update, delete, apply, scan, simulate, wait_for). Domain nouns are used consistently across resources (ceph_, sdn_, firewall_, ha_, node_, vm_, container_). No camelCase or ad-hoc naming anywhere.
156 tools is far beyond what an agent can hold in context comfortably, even though the Proxmox domain is genuinely vast (nodes, VMs, containers, storage, Ceph, SDN, firewall, HA, auth, backup, replication, notifications). Most tools are non-redundant and well-scoped individually, but the flat single-level namespace offers no grouping or progressive disclosure, so discovery cost is high.
Coverage is unusually broad: full read/write lifecycles for guests, storage, Ceph, SDN, firewall, HA, users/ACLs, backups, replication and notifications, plus safety pre-checks (check_ceph_safety, check_vm_migration) and dry-runs (preview_backup_prune, get_sdn_pending_diff). Minor gaps remain โ package updates explicitly cannot be installed, SDN fabrics and route policies are read-only, and there is no guest console/exec or VNC access โ but these are narrow and documented rather than dead ends.
Maintenance
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Gainium โ manage trading bots, deals, and balances via AI assistants
MCP server for AI dialogue using various LLM models via AceDataCloud
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for managing Proxmox VE clusters โ provision VMs and containers, manage snapshots and backups, execute commands, browse storage, and monitor resources through natural language37289 PyPI18MIT
- AlicenseAqualityBmaintenanceMinimal MCP server for Proxmox VE โ 38 tools for nodes, VMs, LXC, storage, and snapshots. Read-only by default, single Docker image, multi-arch.3881 PyPI7MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Proxmox VE that enables AI assistants to inspect and manage LXC containers, VMs, snapshots, and resource pools via the Proxmox API.-
- AlicenseAqualityDmaintenanceMCP server for managing Proxmox VE resources, VM/CT lifecycle, snapshots, backups, and clones via natural language.23MIT