# proxmox-mcp [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/lidless-labs/proxmox-mcp  
**GitHub Stars:** 11  
**npm Downloads (last month):** 538  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/proxmox-mcp

## Description
Point an agent at your homelab and it can nuke a VM. proxmox-mcp gates every write before the Proxmox API sees it, so an AI client can operate the cluster without owning it.

## Tools
Capabilities this server exposes over MCP:

- **proxmox_status** — Get PVE version + per-node status (online state, CPU, memory, uptime) via GET /version + GET /cluster/resources?type=node.
- **proxmox_list_containers** — List every LXC container across the cluster (vmid, name, node, status, CPU/mem) via GET /cluster/resources?type=vm filtered client-side to type=lxc.
- **proxmox_list_vms** — List every QEMU VM across the cluster (vmid, name, node, status, CPU/mem) via GET /cluster/resources?type=vm filtered client-side to type=qemu.
- **proxmox_get_resource** — Get full current status for one LXC or VM by vmid (resolves node+type from cluster resources, then GET /nodes/{node}/{type}/{vmid}/status/current).
- **proxmox_get_vm_config** — Get QEMU VM config by vmid (GET /nodes/{node}/qemu/{vmid}/config). Fails if the vmid is not a QEMU VM.
- **proxmox_get_container_config** — Get LXC container config by vmid (GET /nodes/{node}/lxc/{vmid}/config). Fails if the vmid is not an LXC container.
- **proxmox_validate_qemu_smoke_source** — Validate that a QEMU VM is a safe live-smoke clone source. Checks passthrough devices, guest agent, running state, and disk size before cloning.
- **proxmox_audit_permissions** — Read effective Proxmox permissions for the current token or a specified user/token across smoke-relevant paths (GET /access/permissions).
- **proxmox_recent_tasks** — List recent cluster tasks (UPID, type, status, node, user, timing) via GET /cluster/tasks. Optionally filter by vmid (post-filter client-side).
- **proxmox_list_backups** — List backup volumes on a node. Walks each backup-capable storage via GET /nodes/{node}/storage/{storage}/content?content=backup. Optionally filter by vmid.
- **proxmox_resource_usage** — Get historical CPU/memory/disk/network samples for one LXC or VM via GET /nodes/{node}/{type}/{vmid}/rrddata?timeframe=<hour|day|week>.
- **proxmox_start_resource** — Start a stopped LXC container or QEMU VM by vmid. Tier-2 write; requires confirm:true.
- **proxmox_stop_resource** — Gracefully shutdown an LXC container or QEMU VM by vmid (POST status/shutdown). Tier-2 write; requires confirm:true.
- **proxmox_reboot_resource** — Reboot an LXC container or QEMU VM by vmid (POST status/reboot). Tier-2 write; requires confirm:true.
- **proxmox_snapshot_resource** — Create a snapshot of an LXC container or QEMU VM by vmid (POST /snapshot with {snapname, description?}). Tier-2 write; requires confirm:true.
- **proxmox_rollback_snapshot** — Roll back an LXC container or QEMU VM to a named snapshot. Tier-3 destructive because it reverts guest state; requires confirm:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_run_backup** — Trigger a vzdump backup of a single vmid to a target storage (POST /nodes/{node}/vzdump with {vmid, storage, mode, compress:'zstd'}). Tier-2 write; requires confirm:true.
- **proxmox_get_task_status** — Get the current status of a Proxmox task by UPID (running/stopped, exit status) via GET /nodes/{node}/tasks/{upid}/status. Node is parsed from the UPID.
- **proxmox_get_task_log** — Tail a Proxmox task log by UPID via GET /nodes/{node}/tasks/{upid}/log?start=N&limit=M. Node is parsed from the UPID. Returns { lines, total }.
- **proxmox_list_templates** — List available LXC container templates (vztmpl) and/or VM ISOs on a node/storage (GET /nodes/{node}/storage/{storage}/content?content=vztmpl|iso). Defaults to both kinds on storage 'local'.
- **proxmox_list_storage** — List Proxmox storage status on one node or all nodes via GET /nodes/{node}/storage.
- **proxmox_list_snapshots** — List snapshots for one LXC container or QEMU VM via GET /nodes/{node}/{type}/{vmid}/snapshot.
- **proxmox_guest_network** — Return guest network interfaces and usable IPv4 addresses for a QEMU VM via guest agent or an LXC container via its interfaces endpoint.
- **proxmox_wait_task** — Poll a Proxmox task by UPID until it stops or the timeout expires. Returns done:false on timeout with the last status.
- **proxmox_next_vmid** — Return the next available Proxmox VMID via GET /cluster/nextid.
- **proxmox_list_pool_resources** — List resources assigned to a Proxmox pool (GET /pools/{pool}). Defaults to the mcp-smoke pool for smoke-test audits.
- **proxmox_create_container** — Create a new LXC container on a node (POST /nodes/{node}/lxc) with sensible defaults (storage local-lvm, 512MiB, 1 core, 8GB rootfs, DHCP net). Tier-2 write; requires confirm:true.
- **proxmox_create_vm** — Create a new QEMU VM on a node (POST /nodes/{node}/qemu) with sensible defaults (2GiB, 2 cores, 32GB disk on local-lvm, virtio net). Optionally attaches an ISO as ide2 cdrom. Tier-2 write; requires confirm:true.
- **proxmox_clone_resource** — Clone an existing LXC or QEMU resource by source_vmid to a new_vmid (POST /nodes/{node}/{type}/{source_vmid}/clone). Resolves source node/type from cluster resources. Tier-2 write; requires confirm:true.
- **proxmox_destroy_resource** — Permanently delete an LXC container or QEMU VM by vmid (DELETE /nodes/{node}/{type}/{vmid}). Tier-3 destructive; requires confirm:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_cleanup_smoke_resources** — Preview or destroy smoke-test LXC/QEMU resources from a pool when their names match the smoke prefix. Defaults to dry_run:true. Actual deletion requires dry_run:false, confirm:true, destructive:true, and PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_delete_snapshot** — Delete a named snapshot from an LXC container or QEMU VM (DELETE /nodes/{node}/{type}/{vmid}/snapshot/{snapname}). Tier-3 destructive; requires confirm:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_force_stop_resource** — Hard-kill an LXC container or QEMU VM (POST /nodes/{node}/{type}/{vmid}/status/stop). Unlike reboot/shutdown this is a non-graceful stop. Tier-3 destructive; requires confirm:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_exec** — Run a shell command inside an LXC container (via SSH+pct exec) or QEMU VM (via direct SSH by default, or the qemu-guest-agent API when PROXMOX_EXEC_BACKEND=guest-agent - no in-guest SSH key needed). Returns stdout/stderr/exit_code. Tier-2 write; requires confirm:true.
- **proxmox_read_file** — Read a file from inside an LXC container or QEMU VM. Gated guest read; requires confirm:true.
- **proxmox_write_file** — Write a text file to a path inside an LXC container or QEMU VM. Creates parent directories. Tier-2 write; requires confirm:true.
- **proxmox_stat_path** — Return structured metadata for a path inside an LXC container or QEMU VM. Gated guest read; requires confirm:true.
- **proxmox_list_directory** — List one directory inside an LXC container or QEMU VM. Gated guest read; requires confirm:true.
- **proxmox_service_status** — Return systemd service status from inside an LXC container or QEMU VM. Gated guest read; requires confirm:true.
- **proxmox_service_start** — Start a systemd service inside an LXC container or QEMU VM. Tier-2 write; requires confirm:true.
- **proxmox_service_stop** — Stop a systemd service inside an LXC container or QEMU VM. Tier-2 write; requires confirm:true.
- **proxmox_service_restart** — Restart a systemd service inside an LXC container or QEMU VM. Tier-2 write; requires confirm:true.
- **proxmox_update_vm_config** — Edit an existing QEMU VM's config (PUT /nodes/{node}/qemu/{vmid}/config): cores, memory, sockets, balloon, name, description, onboot, tags, plus arbitrary keys via `set` and key removal via `unset`. Some changes (CPU/mem/disk on a running VM) apply as pending until reboot. Tier-2 write; requires confirm:true.
- **proxmox_update_container_config** — Edit an existing LXC container's config (PUT /nodes/{node}/lxc/{vmid}/config): cores, memory, swap, hostname, nameserver, description, onboot, tags, plus arbitrary keys via `set` and key removal via `unset`. Tier-2 write; requires confirm:true.
- **proxmox_resize_disk** — Grow a VM or container disk (PUT /nodes/{node}/{type}/{vmid}/resize) with {disk,size}. Size is absolute ('32G') or an increment ('+2G'); Proxmox only grows disks. Tier-2 write; requires confirm:true.
- **proxmox_restore_backup** — Restore a vzdump/PBS backup into a VMID (POST /nodes/{node}/{type}/{vmid} with restore=1). Restoring to a new VMID is Tier-2 (confirm:true). Overwriting an EXISTING VMID wipes its disks and additionally requires force:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_migrate_resource** — Migrate a VM or container to another node (POST /nodes/{node}/{type}/{vmid}/migrate). QEMU supports online (live) migration; LXC uses restart mode. Tier-2 write; requires confirm:true.
- **proxmox_suspend_resource** — Suspend (pause) a running LXC or QEMU guest (POST /nodes/{node}/{type}/{vmid}/status/suspend). QEMU can suspend to disk with todisk:true. Tier-2 write; requires confirm:true.
- **proxmox_resume_resource** — Resume a suspended LXC or QEMU guest (POST /nodes/{node}/{type}/{vmid}/status/resume). Tier-2 write; requires confirm:true.
- **proxmox_reset_resource** — Hard-reset a running QEMU VM (POST /nodes/{node}/qemu/{vmid}/status/reset) - equivalent to the reset button, no graceful shutdown. QEMU only. Tier-2 write; requires confirm:true.
- **proxmox_convert_to_template** — Convert a stopped VM or container into a template (POST /nodes/{node}/{type}/{vmid}/template). One-way: a template cannot be started, only cloned from. Tier-2 write; requires confirm:true.
- **proxmox_list_storage_content** — List volumes on a storage (GET /nodes/{node}/storage/{storage}/content): ISOs, container templates, disk images, and backups, with size + owning vmid. Optionally filter by content type or vmid. Tier-1 read.
- **proxmox_download_url** — Download an ISO or container template from a URL onto a storage (POST /nodes/{node}/storage/{storage}/download-url). Optional checksum verification. Tier-2 write; requires confirm:true.
- **proxmox_delete_volume** — Permanently delete a storage volume - a backup archive, ISO, template, or disk image (DELETE /nodes/{node}/storage/{storage}/content/{volume}). Tier-3 destructive; requires confirm:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_list_node_services** — List the Proxmox host's systemd services and their state (GET /nodes/{node}/services): pveproxy, pvedaemon, pve-cluster, corosync, etc. Tier-1 read.
- **proxmox_list_updates** — List pending APT package updates on a node (GET /nodes/{node}/apt/update): package, current and candidate versions. Read-only; does not refresh the index or install anything. Note: Proxmox gates this endpoint behind the Sys.Modify privilege, so an audit-only token gets 403. Tier-1 read.
- **proxmox_list_disks** — List a node's physical disks with model, size, type, SMART health and wearout (GET /nodes/{node}/disks/list). Tier-1 read.
- **proxmox_cancel_task** — Stop a running Proxmox task by UPID (DELETE /nodes/{node}/tasks/{upid}) - e.g. abort a stuck migration or backup. The node is parsed from the UPID. Tier-2 write; requires confirm:true.
- **proxmox_node_power** — Reboot or shut down an entire Proxmox node (POST /nodes/{node}/status), which takes down every guest on it. Tier-3 destructive; requires confirm:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_list_firewall_rules** — List firewall rules at the cluster, node, or guest scope (GET {base}/firewall/rules). Returns rule position, action, direction, and match fields. Tier-1 read.
- **proxmox_get_firewall_options** — Read firewall options at the cluster, node, or guest scope (GET {base}/firewall/options): whether the firewall is enabled, default in/out policy, logging. Tier-1 read.
- **proxmox_add_firewall_rule** — Add a firewall rule at the cluster, node, or guest scope (POST {base}/firewall/rules). Tier-2 write; requires confirm:true.
- **proxmox_delete_firewall_rule** — Delete a firewall rule by position at the cluster, node, or guest scope (DELETE {base}/firewall/rules/{pos}). Tier-2 write; requires confirm:true.
- **proxmox_set_firewall_enabled** — Enable or disable the firewall at the cluster, node, or guest scope (PUT {base}/firewall/options with enable). Note: the cluster-level switch gates all others. Tier-2 write; requires confirm:true.
- **proxmox_move_disk** — Relocate a VM disk (POST /nodes/{node}/qemu/{vmid}/move_disk) or container volume (POST /nodes/{node}/lxc/{vmid}/move_volume) to another storage. Optionally deletes the source after a successful copy. Tier-2 write; requires confirm:true.
- **proxmox_list_storage_config** — List datacenter storage definitions (GET /storage): id, type, allowed content, node restrictions, shared/disabled flags. This is the cluster storage configuration, distinct from per-node status. Tier-1 read.
- **proxmox_create_storage** — Define a new datacenter storage (POST /storage) of a given type with content types and type-specific keys via `options`. Tier-2 write; requires confirm:true.
- **proxmox_delete_storage** — Remove a storage definition from the datacenter config (DELETE /storage/{id}). Does not erase the underlying data, but detaches it from Proxmox. Tier-3 destructive; requires confirm:true, destructive:true, and env PROXMOX_ENABLE_DESTRUCTIVE=1.
- **proxmox_list_backup_jobs** — List scheduled backup (vzdump) jobs (GET /cluster/backup): id, schedule, target storage, selection, and enabled state. Tier-1 read.
- **proxmox_create_backup_job** — Create a scheduled backup (vzdump) job (POST /cluster/backup). Specify a schedule + storage and a selection (all, vmid list, or pool). Tier-2 write; requires confirm:true.
- **proxmox_delete_backup_job** — Delete a scheduled backup job by id (DELETE /cluster/backup/{id}). Removes the schedule only; existing backup archives are untouched. Tier-2 write; requires confirm:true.
- **proxmox_list_users** — List Proxmox access users (GET /access/users): userid, realm, enabled/expire state, comment. Tier-1 read.
- **proxmox_list_roles** — List Proxmox roles and their privileges (GET /access/roles). Tier-1 read.
- **proxmox_list_acl** — List access-control entries (GET /access/acl): which user/group/token holds which role on which path, and whether it propagates. Tier-1 read.
- **proxmox_list_pools** — List all resource pools (GET /pools) with their comments. Use proxmox_list_pool_resources for a pool's members. Tier-1 read.
- **proxmox_list_tokens** — List API tokens for a user (GET /access/users/{userid}/token). Secrets are never returned by Proxmox after creation. Tier-1 read.
- **proxmox_set_acl** — Grant or remove a role for a user/token or group on a path (PUT /access/acl). Set remove:true to revoke. Tier-2 write; requires confirm:true.
- **proxmox_create_token** — Create an API token for a user (POST /access/users/{userid}/token/{tokenid}). Returns the secret ONCE - it cannot be retrieved later. With privsep (default), grant it access separately via proxmox_set_acl. Tier-2 write; requires confirm:true.
- **proxmox_delete_token** — Revoke an API token (DELETE /access/users/{userid}/token/{tokenid}). Immediately invalidates the token. Tier-2 write; requires confirm:true.
- **proxmox_create_pool** — Create a resource pool (POST /pools). Add guests/storage to it with proxmox_update_pool. Tier-2 write; requires confirm:true.
- **proxmox_update_pool** — Add or remove guests/storage in a resource pool, or update its comment (PUT /pools/{poolid}). Set remove:true to detach the listed members. Tier-2 write; requires confirm:true.
- **proxmox_delete_pool** — Delete a resource pool (DELETE /pools/{poolid}). Proxmox requires the pool to be empty first; guests/storage are not deleted, only the grouping. Tier-2 write; requires confirm:true.
- **proxmox_cluster_status** — Cluster membership + quorum: each node's id, IP, online state, and (on a cluster) the quorate flag. (GET /cluster/status). Tier-1 read.
- **proxmox_ha_status** — Current HA manager status: quorum, fencing/CRM state, and per-resource HA state. (GET /cluster/ha/status/current). Tier-1 read.
- **proxmox_list_ha_resources** — HA-managed resources (sid, state, group/comment). (GET /cluster/ha/resources). Tier-1 read.
- **proxmox_list_ha_rules** — HA rules (PVE 9+ replacement for HA groups): node affinity and resource placement. (GET /cluster/ha/rules). Tier-1 read.
- **proxmox_list_replication** — Storage replication jobs (id, source guest, target node, schedule). (GET /cluster/replication). Tier-1 read.
- **proxmox_list_sdn_zones** — Software-defined-networking zones. (GET /cluster/sdn/zones). Tier-1 read.
- **proxmox_list_sdn_vnets** — Software-defined-networking virtual networks. (GET /cluster/sdn/vnets). Tier-1 read.
- **proxmox_list_metric_servers** — External metrics servers (InfluxDB/Graphite) configured for the cluster. (GET /cluster/metrics/server). Tier-1 read.
- **proxmox_get_cluster_options** — Read datacenter-wide options (GET /cluster/options): keyboard, MAC prefix, allowed tags, default migration settings, etc. Tier-1 read.
- **proxmox_cluster_log** — Read the recent cluster-wide log (GET /cluster/log): task start/end, auth, and daemon messages across all nodes. Tier-1 read.
- **proxmox_add_ha_resource** — Place a VM or container under HA management (POST /cluster/ha/resources). Only meaningful on a quorate multi-node cluster. Tier-2 write; requires confirm:true.
- **proxmox_delete_ha_resource** — Remove a VM or container from HA management (DELETE /cluster/ha/resources/{sid}). The guest keeps running; only HA management stops. Tier-2 write; requires confirm:true.
- **proxmox_create_replication** — Create a storage replication job for a guest to another node (POST /cluster/replication). Requires a multi-node cluster with a different target node. Tier-2 write; requires confirm:true.
- **proxmox_delete_replication** — Delete a storage replication job (DELETE /cluster/replication/{id}). Tier-2 write; requires confirm:true.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "proxmox-mcp": {
    "command": "npx",
    "args": ["-y","@solomonneas/proxmox-mcp"],
    "env": {
      "PROXMOX_URL": "",
      "PROXMOX_TOKEN_ID": "",
      "PROXMOX_TOKEN_SECRET": "",
      "PROXMOX_TLS_INSECURE": "",
      "PROXMOX_ENABLE_DESTRUCTIVE": ""
    }
  }
}
```

**Requires environment variables:** `PROXMOX_URL`, `PROXMOX_TOKEN_ID`, `PROXMOX_TOKEN_SECRET`, `PROXMOX_TLS_INSECURE`, `PROXMOX_ENABLE_DESTRUCTIVE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What proxmox-mcp does

proxmox-mcp gives MCP-compatible AI clients a structured interface to Proxmox VE. It can inspect cluster and node status, enumerate QEMU VMs and LXC containers, read guest configuration, review storage and backups, inspect firewall and access-control data, and trace asynchronous Proxmox tasks.

The broader tool surface also supports controlled operations such as starting, stopping, rebooting, snapshotting, backing up, cloning, and creating guests. Guest-oriented tools can read files, inspect paths and services, execute shell commands, and write text files inside LXC containers or QEMU VMs. The project is aimed at homelab and virtualization operations where an agent needs API access but should not receive a general-purpose shell on the host.

## How it works

The server authenticates to Proxmox with an API URL, token ID, and token secret. It communicates with an MCP client over the standard server interface; the example configuration launches the npm package through `npx`.

Tools are organized around write-safety tiers. Read-only calls can run without confirmation. Guest reads and safe state changes require `confirm: true`. Destructive operations require that confirmation, a `destructive: true` request flag, and `PROXMOX_ENABLE_DESTRUCTIVE=1` in the server process environment. The gate rejects an unsafe call before it sends an HTTP request to Proxmox.

Many Proxmox operations return UPIDs. Task tools can list recent tasks, retrieve one task's status or log tail, and poll until completion or timeout.

## Setup and configuration

Configure the MCP client to start the package with `npx -y @solomonneas/proxmox-mcp`, then provide these environment variables:

- `PROXMOX_URL`: Proxmox API endpoint, such as `https://host:8006`.
- `PROXMOX_TOKEN_ID`: Proxmox API token identifier.
- `PROXMOX_TOKEN_SECRET`: API token secret.
- `PROXMOX_TLS_INSECURE`: TLS verification setting; the example uses `false`.
- `PROXMOX_ENABLE_DESTRUCTIVE`: set to `1` only when destructive tools should be eligible.

The destructive environment gate is separate from per-call confirmation, so enabling it does not by itself authorize a destructive request.

## Tools and capabilities

The read-oriented surface includes tools for:

- Cluster, node, HA, quorum, service, disk, update, and resource status.
- VM and container inventory, configuration, templates, snapshots, networks, and VMID allocation.
- Storage definitions, content, usage, backups, scheduled backup jobs, and replication.
- Firewall rules, firewall options, users, roles, ACLs, pools, tokens, and permissions.
- Guest file and service inspection, task tracking, and resource metrics.

Gated operations cover guest commands and file writes, lifecycle changes, snapshots, backups, guest creation, and cloning. The project documents a 96-tool surface, while the available tools and permissions depend on the Proxmox token and target resources.

## Limitations and notes

The project is marked WIP and remains pre-1.0. Proxmox permissions still govern what the API token can access; for example, pending-update inspection requires a token with `Sys.Modify`. Destructive actions remain unavailable unless both the request-level gates and the process environment gate are satisfied. TLS behavior must be configured deliberately, especially for clusters using certificates that the client does not trust.

_Full upstream README: https://allmcps.com/mcp/proxmox-mcp/readme_