proxmox-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PROXMOX_URL | Yes | Address of any node in the cluster, with the port. | |
| PROXMOX_PASSWORD | No | The user's password, used with the username. | |
| PROXMOX_TOOLSETS | No | Optional comma-separated toolsets, to expose fewer tools. Empty means all (except raw). | |
| PROXMOX_USERNAME | No | Used instead of an API token, as user@realm (e.g. mcp@pve). | |
| PROXMOX_API_TOKEN | No | Recommended. The whole API token as user@realm!tokenid=secret. Leave empty to use a username and password. | |
| PROXMOX_AUDIT_LOG | No | Optional. stderr, or a file path inside the container, to log every change as a JSON line. | |
| PROXMOX_ALLOW_EXEC | No | Also allow commands and file access inside VMs through the guest agent. Needs writes. | false |
| PROXMOX_DENY_TOOLS | No | Optional comma-separated tool names never to offer. An unknown name stops the server from starting. | |
| PROXMOX_VERIFY_SSL | No | Leave empty when you set a fingerprint. true: the certificate is publicly trusted. false: skip the check (insecure). | |
| PROXMOX_ALLOW_WRITES | No | Allow changes: start and stop guests, edit configuration, create VMs, snapshots and backups. | false |
| PROXMOX_DEFAULT_NODE | No | Node used when a request doesn't name one. Not needed on a single-node install. | |
| PROXMOX_ALLOW_DELETES | No | Also allow deleting guests, volumes, snapshots, backups and configuration. Needs writes. | false |
| PROXMOX_TLS_FINGERPRINT | No | Recommended for Proxmox's self-signed certificate: its SHA-256 fingerprint. An https URL needs this or PROXMOX_VERIFY_SSL. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for monitoring and managing a Proxmox VE cluster: nodes, VMs (qemu), containers (lxc), storage, backups, snapshots, firewall, HA, SDN, Ceph and access control. Start with proxmox_get_cluster_status, proxmox_list_guests or proxmox_list_nodes. Guests are addressed by VMID; the node is looked up automatically when omitted. Node-scoped tools default to PROXMOX_DEFAULT_NODE or the only node. Long-running operations are Proxmox tasks: by default tools wait for them and report the outcome with the end of the task log; pass wait=false to return the task ID (UPID) and follow it with proxmox_get_task. List tools return {total, returned, items} and take search (case-insensitive substring match), fields (keep only these fields in each item; dot paths reach nested fields) and, on long lists, limit. Use them to fetch only what you need. The server is read-only; write tools are disabled (PROXMOX_ALLOW_WRITES=false).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| proxmox_check_ceph_safetyA | 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. |
| proxmox_check_container_featureA | 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. |
| proxmox_check_container_migrationA | 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. |
| proxmox_check_vm_featureA | 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. |
| proxmox_check_vm_migrationA | 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. |
| proxmox_get_acme_accountA | Get an ACME account's details: CA directory, account URL (location), status, contacts and accepted terms of service. Keys are redacted. |
| proxmox_get_acme_challenge_schemaA | Show which credential fields each ACME DNS API plugin needs (e.g. CF_Token for Cloudflare), to fill |
| proxmox_get_acme_pluginA | Get one ACME challenge plugin's configuration (DNS API, nodes, validation delay). Credential values are redacted. |
| proxmox_get_api_tokenA | Get one API token's settings (privilege separation, expiry, comment) and, when privilege-separated, its own ACL entries. |
| proxmox_get_backup_configA | 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. |
| proxmox_get_backup_jobA | 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). |
| proxmox_get_capacity_reportA | 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. |
| proxmox_get_ceph_configA | Read Ceph configuration: the configuration database ( |
| proxmox_get_ceph_crushB | Get the decompiled CRUSH map (devices, buckets, rules) and the list of CRUSH rule names usable as a pool's crush_rule. |
| proxmox_get_ceph_flagsA | Show which cluster-wide Ceph OSD flags are set (noout, noscrub, nodeep-scrub, norebalance, pause...). Change them with proxmox_set_ceph_flags. |
| proxmox_get_ceph_logB | Read lines of the Ceph cluster log (ceph.log) from a node: health changes, OSD up/down events, slow ops and scrub errors. |
| proxmox_get_ceph_metadataA | 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. |
| proxmox_get_ceph_osdA | Get one OSD's details: daemon metadata (devices, BlueStore, memory, version) and its logical volume info (block/DB/WAL devices). |
| proxmox_get_ceph_poolA | 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. |
| proxmox_get_ceph_statusA | 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. |
| proxmox_get_cluster_configA | 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. |
| proxmox_get_cluster_logA | Read recent entries of the cluster log (task starts/ends, logins and other cluster events from all nodes). |
| proxmox_get_cluster_optionsA | 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. |
| proxmox_get_cluster_statusA | 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. |
| proxmox_get_containerA | 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. |
| proxmox_get_container_configA | 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. |
| proxmox_get_container_interfacesA | 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. |
| proxmox_get_container_statsA | 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. |
| proxmox_get_custom_cpu_modelA | Get one custom CPU model definition, including its digest. |
| proxmox_get_disk_smartA | Get a disk's SMART health and attributes (ATA attribute table, or the text report for NVMe/SAS). |
| proxmox_get_firewall_logA | 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 |
| proxmox_get_firewall_optionsA | 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). |
| proxmox_get_firewall_ruleA | Get one firewall rule by position at any level (cluster, node, guest or security group), with its digest for safe updates. |
| proxmox_get_groupB | Get a group's members and comment. |
| proxmox_get_guest_filesystemsA | 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. |
| proxmox_get_guest_firewall_statusA | 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. |
| proxmox_get_guest_infoA | 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 |
| proxmox_get_guest_memory_blocksA | 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. |
| proxmox_get_guest_networkA | 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. |
| proxmox_get_guest_usersA | List the users currently logged in to a running VM (QEMU guest agent get-users), with domain and login time. VMs only. |
| proxmox_get_ha_groupA | Get one HA group's configuration (PVE 8; deprecated in PVE 9 in favour of HA rules). |
| proxmox_get_ha_resourceA | Get one HA resource's configuration, its current status, and the HA rules that reference it (PVE 9+). |
| proxmox_get_ha_ruleA | Get one HA rule (PVE 9+) with its digest. |
| proxmox_get_ha_statusA | 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. |
| proxmox_get_import_metadataA | 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+). |
| proxmox_get_next_vmidA | Get the next free VM/container ID, or check whether a specific ID is free. |
| proxmox_get_node_capabilitiesA | 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. |
| proxmox_get_node_certificatesA | 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. |
| proxmox_get_node_configA | 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. |
| proxmox_get_node_dnsA | Get a node's DNS resolver settings: search domain and up to three name servers. |
| proxmox_get_node_hostsA | Read a node's /etc/hosts file and its digest (pass the digest to proxmox_set_node_hosts to avoid overwriting concurrent edits). |
| proxmox_get_node_journalC | 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. |
| proxmox_get_node_netstatA | Traffic counters of the guests' tap/veth network devices on a node (bytes in/out per device and VMID), as seen from the host. |
| proxmox_get_node_network_interfaceA | Get the configuration of one network interface on a node (as stored in /etc/network/interfaces, including pending changes). |
| proxmox_get_node_package_versionsA | List the installed versions of the important Proxmox packages on a node (like |
| proxmox_get_node_reportA | 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. |
| proxmox_get_node_statsA | 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. |
| proxmox_get_node_statusA | 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. |
| proxmox_get_node_subscriptionA | Get a node's subscription status, level, product, sockets and next due date. The key itself is never shown. |
| proxmox_get_node_syslogA | 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. |
| proxmox_get_node_timeA | Get a node's current time (UTC), local time and configured time zone. Useful for spotting clock drift between nodes. |
| proxmox_get_notification_endpointA | 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). |
| proxmox_get_notification_matcherA | Get one notification matcher's rules and targets (plus its digest for safe updates). |
| proxmox_get_notification_matcher_fieldsA | List the metadata fields notifications carry (type, hostname, job-id...) and their known values, for writing match_field rules in proxmox_save_notification_matcher. |
| proxmox_get_package_changelogA | 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. |
| proxmox_get_permissionsA | 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 |
| proxmox_get_poolA | Get a resource pool's comment and members: guests (status, node, CPU/memory use) and storage (usage). |
| proxmox_get_realmB | Get an authentication realm's configuration (servers, base DN, sync options, OpenID issuer...). Bind passwords and client keys are redacted. |
| proxmox_get_replication_jobA | Get one replication job's configuration (with digest for safe updates) and its current status on the source node. |
| proxmox_get_replication_logA | Read the log of a replication job's last run from the source node, e.g. to diagnose a failing job. |
| proxmox_get_resource_mappingA | Get one PCI, USB or directory resource mapping with its per-node entries and digest. |
| proxmox_get_roleB | Get the privileges of one role, grouped by area (VM, Datastore, Sys...). |
| proxmox_get_sdn_ipam_statusA | 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. |
| proxmox_get_sdn_objectA | 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 |
| proxmox_get_sdn_pending_diffA | 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. |
| proxmox_get_sdn_statusA | 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. |
| proxmox_get_snapshotA | 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. |
| proxmox_get_storageA | Get one storage definition (full config, secrets redacted) and its status/usage on each node. Pass |
| proxmox_get_storage_statsA | 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. |
| proxmox_get_taskA | Get a task's status (running/stopped), exit status and the last lines of its log. |
| proxmox_get_task_logA | Read a task's log, paging from the start (or the end with tail=true). |
| proxmox_get_userA | Get one user's configuration: enabled state, expiry, name, email, groups, comment, API tokens and TFA entries. For effective permissions use proxmox_get_permissions. |
| proxmox_get_versionA | Get the Proxmox VE version and release of the API endpoint this server talks to. |
| proxmox_get_vmA | 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. |
| proxmox_get_vm_cloudinitA | 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. |
| proxmox_get_vm_configA | 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 |
| proxmox_get_vm_statsA | 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. |
| proxmox_get_volumeB | Get a volume's attributes: path on disk, format, size, used space, notes and protection flag. |
| proxmox_get_vzdump_defaultsA | Show the vzdump defaults a node applies to backups (from /etc/vzdump.conf, merged with a storage's settings when |
| proxmox_get_zfs_poolA | Get a zpool's detailed status (like |
| proxmox_list_aclA | 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. |
| proxmox_list_acme_accountsB | List the cluster's registered ACME accounts (used to order node certificates), with their CA directory and contacts. |
| proxmox_list_acme_directoriesA | List the known ACME CA directories (Let's Encrypt production/staging...). With |
| proxmox_list_acme_pluginsB | List the cluster's ACME challenge plugins (standalone HTTP and DNS API plugins). Credentials in plugin data are redacted; only their keys are shown. |
| proxmox_list_all_snapshotsA | 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. |
| proxmox_list_api_tokensA | 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. |
| proxmox_list_appliance_templatesA | 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 |
| proxmox_list_backup_filesA | 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. |
| proxmox_list_backup_jobsA | 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. |
| proxmox_list_backupsA | 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. |
| proxmox_list_ceph_fsA | List CephFS file systems with their metadata and data pools. MDS daemons serving them are listed by proxmox_list_ceph_services. |
| proxmox_list_ceph_osdsA | 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. |
| proxmox_list_ceph_poolsA | 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. |
| proxmox_list_ceph_servicesA | 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. |
| proxmox_list_containersA | 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. |
| proxmox_list_custom_cpu_modelsA | 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. |
| proxmox_list_directory_mountsB | List the directory storages Proxmox manages on a node's disks (filesystems mounted under /mnt/pve/ via systemd mount units). |
| proxmox_list_disksA | 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. |
| proxmox_list_firewall_aliasesA | List IP/network aliases defined at datacenter (cluster) or guest level. Aliases are named addresses usable in rule source/dest. |
| proxmox_list_firewall_groupsA | 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. |
| proxmox_list_firewall_ipsetsA | 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. |
| proxmox_list_firewall_macrosB | List the predefined firewall macros (SSH, HTTP, DNS, Ceph, ...) usable as a rule's |
| proxmox_list_firewall_refsA | 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). |
| proxmox_list_firewall_rulesA | 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. |
| proxmox_list_groupsB | List user groups with their members and comments. |
| proxmox_list_guestsA | 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. |
| proxmox_list_ha_groupsA | 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). |
| proxmox_list_ha_resourcesB | 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). |
| proxmox_list_ha_rulesB | 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). |
| proxmox_list_lvmB | List a node's LVM volume groups with size, free space and physical volumes. |
| proxmox_list_lvm_thinA | 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. |
| proxmox_list_metric_serversB | List external metric servers (InfluxDB, Graphite, OpenTelemetry) that Proxmox sends performance data to. |
| proxmox_list_node_mdev_typesA | 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. |
| proxmox_list_node_networkA | 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. |
| proxmox_list_node_pci_devicesA | 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. |
| proxmox_list_node_repositoriesA | 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. |
| proxmox_list_node_servicesA | 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. |
| proxmox_list_node_updatesA | 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. |
| proxmox_list_node_usb_devicesA | 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. |
| proxmox_list_nodesB | List the cluster's nodes with online state, CPU and memory usage, uptime and subscription level. |
| proxmox_list_notification_matchersC | List notification matchers: rules that route notifications (by severity, metadata fields such as type/hostname/job-id, and calendar time) to targets. |
| proxmox_list_notification_targetsA | 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. |
| proxmox_list_poolsA | 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. |
| proxmox_list_privilegesA | 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. |
| proxmox_list_realm_sync_jobsB | List scheduled realm sync jobs (periodic LDAP/AD/OpenID user and group sync) with schedule, last and next run. |
| proxmox_list_realmsB | List authentication realms (pam, pve, LDAP, Active Directory, OpenID Connect) with type, TFA provider and comment. |
| proxmox_list_replication_jobsA | 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. |
| proxmox_list_resource_mappingsA | 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. |
| proxmox_list_resourcesA | 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. |
| proxmox_list_rolesA | 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. |
| proxmox_list_sdn_fabricsA | List SDN fabrics (PVE 9 underlay networks: OpenFabric, OSPF, WireGuard, BGP) with their nodes. Give |
| proxmox_list_sdn_objectsA | 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. |
| proxmox_list_sdn_route_policiesA | 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). |
| proxmox_list_snapshotsA | 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. |
| proxmox_list_storageA | 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. |
| proxmox_list_storage_contentA | 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). |
| proxmox_list_tasksA | List Proxmox tasks (backups, migrations, starts, clones...). Without |
| proxmox_list_tfaA | 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. |
| proxmox_list_unbacked_guestsA | 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. |
| proxmox_list_usersA | 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. |
| proxmox_list_vmsA | 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 |
| proxmox_list_zfs_poolsA | 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. |
| proxmox_preview_backup_pruneA | Dry run of pruning a backup storage: shows which backups the retention rules (the storage's own, or |
| proxmox_scan_storageA | 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. |
| proxmox_simulate_scheduleA | 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. |
| proxmox_wait_for_taskA | Wait until a running task finishes (or the timeout passes) and return its outcome and log tail. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| backup_audit | Check that every guest is backed up, backups are recent and succeeding, and retention is sensible. |
| capacity_planning | Analyse CPU, memory and storage headroom across nodes and suggest rebalancing or upgrades. |
| cluster_health_check | Overall health review of the Proxmox cluster: quorum, nodes, guests, storage, Ceph, HA, backups and recent failed tasks. |
| deploy_vm | Plan and create a new VM, from a template (cloud-init) or an ISO, choosing node, storage and network sensibly. |
| security_review | Review users, tokens, permissions, firewall, certificates and updates for security issues. |
| snapshot_cleanup | Find old or forgotten snapshots across all guests and propose which to delete. |
| troubleshoot_guest | Investigate why a VM or container is down, slow or unreachable. |
| update_review | List pending package updates on every node and propose a safe rolling upgrade order. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.