get_nodesLABSCO SUMMARY
Long-running Proxmox tasks get a job id, so an agent can come back to them.
Backups and restores outlive a tool call, and this is one of the few Proxmox bridges that says so: jobs are persisted with a Proxmox UPID, and can be polled, cancelled or retried later. The other thing worth noticing is what is off by default — the SSH-backed command execution tools are not registered at all unless you add an ssh section, and the highest-risk ones want an approval token.
What it is
A Proxmox VE control plane exposed twice: as MCP tools for agents, and as an OpenAPI surface for HTTP automation. Async Proxmox tasks get durable job records.
What you get
- Nodes and cluster — get_nodes, get_node_status, get_storage, get_cluster_status, plus get_node_syslog, get_cluster_log, get_task_log and firewall logs
- VMs — get_vms, create_vm, clone_vm, start_vm, stop_vm, shutdown_vm, reset_vm, delete_vm, get_vm_config, set_vm_description and execute_vm_command through the guest agent
- Containers — get_containers, create_container, start_container, stop_container, restart_container, delete_container, update_container_resources, get_container_config, get_container_ip, plus execute_container_command and update_container_ssh_keys when SSH is configured
- Snapshots — list_snapshots, create_snapshot, delete_snapshot and rollback_snapshot, for both qemu and lxc
- Backups and images — list_backups, create_backup, restore_backup, delete_backup, list_isos, list_templates, download_iso and delete_iso
- Jobs — list_jobs, get_job, poll_job, cancel_job and retry_job, with stable job ids and Proxmox UPID tracking
- Mutating operations marked as such, with approval tokens on the high-risk ones and a command policy on execution
Requirements
A Proxmox API token scoped to what you actually need. With uvx, host, user, token name and token value go in the client configuration as PROXMOX_* variables. The Docker routes read them from proxmox-config/config.json instead. Add an ssh section only if you want container command execution — those tools are not registered without it. Three runtime paths: uvx proxmox-mcp-plus for MCP stdio from PyPI, docker compose for native MCP over Streamable HTTP at http://localhost:8000/mcp, or the OpenAPI bridge on port 8811.
Setup effort
One command plus a key — uvx proxmox-mcp-plus, then supply credentials
USE CASES
01
Taking a snapshot before you change something
Create it, do the work, and roll back if it goes wrong — same tools for VMs and containers.
02
Running a backup that takes an hour
Start it, get a job id, and check on it later rather than holding a call open.
03
Standing up a container to spec
Create it from a template with the cores, memory and storage you name, then start it.
04
Working out why a node looks unhappy
Read its status, then its syslog and the cluster log around the same window.
49 tools
Listed in project docs. Your client may show a different list.
get_node_statusget_vmscreate_vmclone_vmstart_vmstop_vmshutdown_vmreset_vmdelete_vmexecute_vm_commandget_vm_configset_vm_descriptionget_containersstart_containerstop_containerrestart_containerupdate_container_resourcescreate_containerdelete_containerexecute_container_commandupdate_container_ssh_keysget_container_configset_container_descriptionget_container_iplist_snapshotscreate_snapshotdelete_snapshotrollback_snapshotlist_isoslist_templatesdownload_isodelete_isolist_backupscreate_backuprestore_backupdelete_backuplist_jobsget_jobpoll_jobcancel_jobretry_jobget_storageget_cluster_statusget_node_syslogget_task_logget_cluster_logget_node_firewall_logget_guest_firewall_logBEFORE YOU INSTALL
What to know first
Tools you get
49 tools named in the project's documentation.
Requires
- uvx on PATH
- PROXMOX_TOKEN_NAME in your environment
- PROXMOX_TOKEN_VALUE in your environment
- PROXMOX_HOST in your environment
- PROXMOX_USER in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx proxmox-mcp-plusMCP Clients
Docker — HTTP server
Create proxmox-config/config.json in the directory you run this from, with your Proxmox host, port, user, token name and token value, then start the container:
DOCKER — HTTP SERVER · TERMINAL
export MCP_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 8000:8000 \
-e PROXMOX_MCP_MODE=mcp-http \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=8000 \
-e MCP_TRANSPORT=STREAMABLE_HTTP \
-e MCP_API_KEY="$MCP_API_KEY" \
-v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
ghcr.io/rekklesna/proxmoxmcp-plus:latestThen point your MCP client at port 8000 on the Docker host, path /mcp (http://localhost:8000/mcp on the same machine), and have it send the header Authorization: Bearer followed by the MCP_API_KEY value you exported.
The Docker route reads the Proxmox connection from proxmox-config/config.json in the directory you start it from, not from your client: create it from the repository's proxmox-config/config.example.json and set proxmox.host, proxmox.port, auth.user, auth.token_name and auth.token_value. The uvx route takes the same values as the PROXMOX_* variables in its client configuration.
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"proxmox-mcp-plus": {
"command": "uvx",
"args": [
"proxmox-mcp-plus"
],
"env": {
"PROXMOX_HOST": "<YOUR_PROXMOX_HOST>",
"PROXMOX_USER": "root@pam",
"PROXMOX_TOKEN_NAME": "mcp-token",
"PROXMOX_TOKEN_VALUE": "<YOUR_PROXMOX_TOKEN_VALUE>",
"PROXMOX_PORT": "8006",
"PROXMOX_VERIFY_SSL": "true"
}
}
}
}root@pam and mcp-token are sample values for the API token's user (with its realm) and the token's name.
The Docker route reads the Proxmox connection from proxmox-config/config.json in the directory you start it from, not from your client: create it from the repository's proxmox-config/config.example.json and set proxmox.host, proxmox.port, auth.user, auth.token_name and auth.token_value. The uvx route takes the same values as the PROXMOX_* variables in its client configuration.
