claude-proxmox-controller
Integrates with Proxmox VE hosts to manage containers and virtual machines, including power operations, consoles, files, snapshots, backups, scheduled backup jobs, graphs, host power, and commands inside guests or on the Proxmox host, all governed by per-host permission switches.
Claude Proxmox Controller
Your Proxmox VE hosts in one window — and Claude, working on them as far as you let it.
Proxmox Controller is a desktop app for Windows and Linux. On its own it is a fast home for your hosts: containers and virtual machines, consoles, files, snapshots, backups and graphs, without a browser or a web login. The magic is Claude Access: Claude (Anthropic's AI) can look after your hosts — start and stop guests, create VMs that set themselves up, schedule backups, read logs, run commands inside guests, copy files — through switches you set for each host and requests you approve in a window of the app. You stay in charge of every step.
by the mechanic — built together with Claude
Claude Access: AI on your servers, safely
Claude reaches your hosts only through this app, and only as far as each host's switches allow:
Switch | What it opens | Default |
Read | state, addresses, settings, snapshots, backups, tasks, graphs | On |
Power | start, shut down, stop, reboot, wake | Ask |
Change | new guests, settings, snapshots, backups, backup jobs | Ask |
Destroy | deleting guests, snapshots, backups, Claude's backup jobs; jobs that prune old backups | Off |
Host | the host's own power | Off |
Console | the guest's screen: screenshots, keys, clicks, recordings | Off |
Commands | commands inside guests (QEMU guest agent) | Off |
Files | copying files to and from guests | Off |
Host commands | shell commands on the Proxmox host (SSH) | Off |
Each switch is Off (refused), Ask (a window asks you: Allow, Allow on this guest for an hour — another guest is asked about again — or Deny) or On. The approval window wears yellow-and-black warning stripes, so it is never lost among other windows. Claude never sees a password: where one is needed, the app asks you for it in its own window. Every request is logged with the reason Claude gave. Claude's token on each host holds only the Proxmox privileges its open switches need. The full list of tools is in docs/claude-access.md.
The switches govern Claude as it works through this app. A program that runs as you on your computer (Claude Code with a shell of its own, too) is outside them: it can read the app's files — the hosts' API tokens and the app's SSH key among them, which are not encrypted, only readable by you alone.
It works with Claude Desktop and Claude Code (the app connects them for you).
Under the hood, Claude Access is a local MCP server: the app registers it with Claude Desktop and Claude Code for you, and every tool call passes through the switches above.
Related MCP server: proxmox-mcp-server
Without AI
Everything works without Claude too:
Hosts — one or many, with Wake-on-LAN, the host's console and upgrade, and its CPU, memory and storage.
Guests — start, shut down, stop, reboot, many at once; notes, tags, boot order; edit cores, memory, disks, display, sound and USB devices.
Consoles — a built-in one (with Paste…: text typed into the guest key by key, even in an installer), or SPICE through virt-viewer for sound, clipboard and USB. Record any console as a video (MP4, with the VM's sound when it has SPICE), for you or for Claude — a desktop, a server's text screen or a container.
Files — this computer on one side, a VM or container on the other: send, receive, drag, and a right-click menu with Rename, Delete, Properties, Permissions and Edit (open a guest's file in your own editor, save, send back).
New VMs that set themselves up — Windows 11 with no setup questions; ready-made Ubuntu Desktop (with Remote Desktop) or Server in minutes; Ubuntu Server from its ISO, installing itself; a static IP if you want one.
Install Guest Agent — for VMs that lack it, typed into their console for you.
Snapshots, backups, scheduled backup jobs, graphs.
Updates — a striped tab tells you when a new version is out; one click installs it.
Install
Windows 10/11 — download the setup from themechanic.store/controller and run it. It installs for your user and offers to add virt-viewer (the SPICE console).
Ubuntu / Debian — download the
.debfrom the same page and open it, or install from the terminal (the package brings virt-viewer with it):sudo apt install ./proxmox-controller_1.2.0_amd64.debUbuntu / Debian, from its apt repository — it then updates with the rest of the system:
wget -qO- https://themechanic.store/apt-controller/proxmox-controller.gpg | sudo tee /usr/share/keyrings/proxmox-controller.gpg >/dev/null echo "deb [signed-by=/usr/share/keyrings/proxmox-controller.gpg] https://themechanic.store/apt-controller ./" | sudo tee /etc/apt/sources.list.d/proxmox-controller.list sudo apt update && sudo apt install proxmox-controllerThe package is built on Ubuntu 24.04 and runs there and on newer releases (tested on Ubuntu Desktop 26.04).
Each host needs a Proxmox API token (Help in the app shows how to make one).
From the source
Linux, Python 3.12+:
./install.shThe tests: .venv/bin/python -I tools/run_tests.py. The packages: packaging/windows/build.py (on Windows, with
PyInstaller and Inno Setup) and packaging/linux/build_deb.py (on Ubuntu 24.04, with PyInstaller and dpkg-deb).
License
MIT — the code is open for anyone to read, use and build on.
Available Tools
47 toolsbackup_nowB
Back a guest up now (it keeps running in snapshot mode).
Inputs: host (required), vmid (required), reason (required), mode, +3 more.
bulk_powerA
Start several guests one after the other in their boot order, or shut them down in reverse order — one Proxmox task, like the web UI's Bulk Actions.
Inputs: host (required), vmids (required), action (required), reason (required), +2 more.
clone_vmC
Copy a VM or a template as a new VM.
Inputs: host (required), vmid (required), reason (required), new_name (required), +3 more.
console_clickA
Click — or double-click, right-click, or turn the wheel (scroll: + up, − down) — on a running guest's screen at x, y of the latest console_screenshot picture (take a fresh one first: the click lands where things are now). For installers and desktops that need the mouse; keys (console_send) are surer where they work. The user sees a red mark where it will land. It needs an absolute pointer in the VM (a USB tablet; Linux also has QEMU's vmmouse): without one it says so and clicks nothing.
Inputs: x (required), y (required), host (required), vmid (required), +4 more.
console_recordA
Record a running guest's console as a video (MP4, H.264), with the VM's sound when it has a SPICE sound card, at the guest's own resolution, with nothing shown on the user's screen. action start begins it — then work in the console as usual (console_send, console_click…): typing, commands and builds all go into the video — and action stop finishes it and says where the file is (the user's Videos folder, Proxmox Controller). status says whether one runs. It stops by itself after max_minutes (60 unless given) or when the guest stops. Works on desktops, servers' text screens and containers (containers without sound).
Inputs: host (required), vmid (required), action (required), reason (required), +2 more.
console_screenshotA
A picture of a running guest's screen — wider screens are shrunk by a whole factor (1920×1080 comes as 960×540). To read small text, give region: that part of the picture comes back at the screen's own pixels. console_click always takes x, y of the whole picture.
Inputs: host (required), vmid (required), reason (required), region.
console_sendA
Type text into a running guest's console and/or press keys: enter, tab, escape, backspace, delete, arrows (up, down, left, right), home, end, pageup, pagedown, f1–f12, and combinations such as ctrl+alt+delete or ctrl+c. Text is typed as on a US keyboard. With text and keys, the text is typed first and the keys pressed after it (type a command, then enter). For another order — keys first, or several of each — give steps instead, done in their order: for example [{"keys": ["ctrl+l"]}, {"text": "example.org"}, {"keys": ["enter"]}].
Inputs: host (required), vmid (required), reason (required), keys, +2 more.
console_type_passwordA
Type a password into a running guest's console — at a login, a sudo prompt, or an installer's password screen. The USER types it in Proxmox Controller's window (with a picture of the screen); you never give or see it. Enter is pressed after it unless enter is false. A screen with a second field to repeat it (an installer's 'Confirm password'): put the cursor in the first and give confirm_at = [x, y] of the second, from the latest console_screenshot picture — the user types it twice in the window (so a typo shows); the app types it, clicks there, and types it again. confirm (Tab instead of the click) only where Tab goes straight to the second field — check that first with an empty field: a 'Show' button between them would get it. Where the repeat is on a screen of its own, call this twice instead.
Inputs: host (required), vmid (required), reason (required), enter, +2 more.
create_backup_jobADestructive
Schedule backups: a backup job that Proxmox runs by itself at its time. schedule as Proxmox writes it — 03:00 (every day), mon..fri 21:30, sat,sun 02:00, sun 04:00, or any Proxmox calendar event (*/6:00). Guests: vmids, or all (with exclude). storage: one that takes backups. keep (how many backups to keep: last, daily, weekly, monthly) makes Proxmox delete the older backups of these guests on that storage after each run: it needs the Destroy switch; without keep, the storage's own rule applies. The job gets an ID beginning with claude-.
Inputs: host (required), reason (required), storage (required), schedule (required), +9 more.
create_cloud_vmA
Create an Ubuntu VM from a cloud image (see get_cloud_image) — no installer: a user, its password (the USER types it in Proxmox Controller's window; you never give or see a password), optionally an SSH public key, network by DHCP. It sets itself up on the first start, from a setup disc the app makes and deletes afterwards: the updates and the QEMU guest agent (a server: 2-5 minutes). edition 'desktop' adds a SPICE display, sound and a USB tablet, and installs Ubuntu Desktop too (10-20 minutes); remote_desktop turns on Ubuntu's own Remote Desktop (GNOME Remote Desktop: RDP, port 3389, the Ubuntu desktop itself with its sound) with the same user and password; dark_theme makes the desktop dark.
Inputs: host (required), name (required), image (required), reason (required), +17 more.
create_containerB
Create an unprivileged container from a template (see list_install_media). Its root password is typed by the USER in Proxmox Controller's window (you never give or see it); an SSH public key can be added.
Inputs: host (required), reason (required), hostname (required), template (required), +14 more.
create_vmA
Create a VM that boots an ISO image (see list_install_media). Profiles: linux, win11 (UEFI, Secure Boot, TPM 2.0), win10, other. It gets a SPICE display, sound and a USB tablet. Windows (win11/win10) installs itself with windows_user: the app puts an answer file on a disc of its own — VirtIO drivers from virtio_iso, the edition, no setup questions, that user with a password the USER types in Proxmox Controller's window (you never give or see it), optionally Remote Desktop and the dark theme, and the VirtIO guest tools with the QEMU guest agent last; with start, the app presses Enter at the installer's 'Press any key to boot from CD' itself (it waits only seconds). The disc is deleted once Windows is ready. An Ubuntu Server ISO from 24.04 on (profile linux) installs itself with linux_user: autoinstall answers on a disc of the app's — that user with the password the USER types, optionally an SSH key and a static_ip, the whole disk, the QEMU guest agent, OpenSSH, the host's time zone; with start, the app types yes at the installer's 'Continue with autoinstall?' itself. About 15 minutes; the disc is deleted once the agent answers.
Inputs: iso (required), host (required), name (required), reason (required), +21 more.
delete_backupBDestructive
Delete a backup (not a protected one).
Inputs: host (required), volid (required), reason (required).
delete_backup_jobADestructive
Delete a backup job Claude made (ID claude-…): its schedule goes, the backups it made stay. The user's own jobs cannot be deleted here.
Inputs: id (required), host (required), reason (required).
delete_guestADestructive
Delete a stopped guest with all its disks and snapshots — and its backups, which Proxmox would keep (protected ones always stay), unless keep_backups is true.
Inputs: host (required), vmid (required), reason (required), keep_backups.
delete_snapshotDDestructive
Delete a snapshot.
Inputs: host (required), vmid (required), reason (required), snapshot (required).
download_isoC
Have the host download an ISO image from a web address.
Inputs: url (required), host (required), reason (required), node, +3 more.
edit_backup_jobADestructive
Change a backup job Claude made (ID claude-…): any of its settings, or enabled to turn it off and on. keep {} goes back to the storage's own rule; a keep with numbers needs the Destroy switch (see create_backup_job). The user's own jobs cannot be changed here.
Inputs: id (required), host (required), reason (required), all, +10 more.
edit_guestB
Change a guest's settings: cores, memory_mib, swap_mib, name, start_at_boot, boot_order, boot_delay_s, shutdown_timeout_s, tags, notes, tablet, cpu_type. Only what is given changes.
Inputs: host (required), vmid (required), reason (required), changes (required).
get_cloud_imageA
Have the host download Ubuntu Server's official cloud image — an LTS release still supported (list_install_media: cloud_images_offered) — once, to make VMs from with create_cloud_vm.
Inputs: host (required), reason (required), node, release, +1 more.
grow_diskA
Make a guest's disk bigger (never smaller).
Inputs: disk (required), host (required), vmid (required), add_gb (required), +1 more.
guest_detailsBRead-onlyIdempotent
One guest's full Proxmox configuration, and for a VM the settings waiting for its next start.
Inputs: host (required), vmid (required).
guest_powerA
Start, shut down (clean), stop (at once, like pulling the plug — only if shut down does not work) or reboot a guest.
Inputs: host (required), vmid (required), action (required), reason (required).
guest_usageARead-onlyIdempotent
A guest's average and peak CPU, memory, network and disk use over the last hour, day, week or month.
Inputs: host (required), vmid (required), timeframe.
host_commandA
Run a shell command on the Proxmox host itself, as root, over the SSH key the user set up in Proxmox Controller, and get its output and exit code — for what the API cannot do (installed programs, services, logs, files). One command line a request: the user sees it as it is in the approval window, every time. It runs on the host at the address the app connects to.
Inputs: host (required), reason (required), command (required), timeout_s.
host_powerBDestructive
Shut down or reboot the host itself (its guests are shut down first).
Inputs: host (required), action (required), reason (required), node.
host_statusCRead-onlyIdempotent
A host's nodes: CPU, memory, system disk, uptime, load, and storage use.
Inputs: host (required).
list_backup_jobsARead-onlyIdempotent
The scheduled backups (Datacenter → Backup) and the guests no job covers. by_claude: a job Claude made (its ID begins with claude-) — only those can Claude change or delete; the user's jobs only the user changes, in the app.
Inputs: host (required).
list_backupsARead-onlyIdempotent
A guest's backups, newest first — also of a guest deleted since, by its old ID.
Inputs: host (required), vmid (required).
list_guest_filesA
The files and folders in a folder of a running VM (through its QEMU guest agent) or container (over the host's SSH): name, folder or not, size, modified. Without folder: /home on Linux, C:\Users on Windows, /root in a container; on Windows an empty folder lists the drives.
Inputs: host (required), vmid (required), reason (required), folder.
list_guestsBRead-onlyIdempotent
Every VM and container of a host: state, CPU, memory, disk, IP addresses, tags, start at boot and boot order, notes.
Inputs: host (required).
list_hostsARead-onlyIdempotent
The Proxmox hosts Proxmox Controller lets you use, whether each is online, and what you may do on each (each kind of request is off, ask — the user approves it — or on). Call this first.
Inputs: no named parameters.
list_install_mediaCRead-onlyIdempotent
What new guests can be made from: ISO images, container templates, storages, network bridges and the next free VMID.
Inputs: host (required), node.
list_snapshotsCRead-onlyIdempotent
A guest's snapshots.
Inputs: host (required), vmid (required).
list_tasksBRead-onlyIdempotent
The host's recent tasks, newest first, with how they ended.
Inputs: host (required), limit.
receive_filesA
Copy files and folders (names) from a folder of a running VM or container into a folder of the user's computer (a whole path that exists). What is there already is not replaced unless replace is true.
Inputs: to (required), host (required), vmid (required), names (required), +3 more.
restore_backupADestructive
Restore a guest's backup as a new guest — or over the guest itself (replace: true; it must be stopped, and that is a Destroy request). A guest deleted since (its backup found by list_backups with its old ID) comes back as itself: its old ID while free, its old MAC.
Inputs: host (required), vmid (required), volid (required), reason (required), +4 more.
rollback_snapshotADestructive
Roll a guest back to a snapshot (what came after it is lost).
Inputs: host (required), vmid (required), reason (required), snapshot (required).
run_backup_jobA
Run a backup job's backup now (its guests, storage and mode), as Run Now does — without its keep: Proxmox prunes at the job's next scheduled run.
Inputs: id (required), host (required), reason (required).
run_commandA
Run a program inside a running VM through the QEMU guest agent and get its output (for example ["systemctl", "status", "nginx"], or ["sh", "-c", "df -h"]). It runs as root (SYSTEM on Windows) unless user is given.
Inputs: host (required), vmid (required), reason (required), command (required), +3 more.
send_filesA
Copy files and folders of the user's computer (whole paths) into a folder of a running VM or container — names and times kept, folders whole. Fast over the network when the guest can reach the computer, otherwise through Proxmox (about 1 MB/s). What is there already is not replaced unless replace is true. The user sees every path in the approval window.
Inputs: host (required), vmid (required), paths (required), folder (required), +3 more.
set_container_root_passwordA
Set a running container's root password to one the USER types in Proxmox Controller's window (you never give or see it) — for a container whose root password is lost, or to give it a new one. It runs pct exec -- chpasswd on the host over the app's SSH key, so it is a host command; the container must be on the node the app connects to.
Inputs: host (required), vmid (required), reason (required).
stop_taskBDestructive
Stop a running task (one started through this connector).
Inputs: host (required), upid (required), reason (required).
take_snapshotC
Take a snapshot of a guest.
Inputs: host (required), name (required), vmid (required), reason (required), +1 more.
task_logCRead-onlyIdempotent
A task's log (a backup's progress, an error).
Inputs: host (required), upid (required), start.
wait_for_requestARead-onlyIdempotent
Go on waiting for a request that came back with status 'waiting' (the user has not answered its approval window yet, or its work is still going): gives that request's answer when there is one, or 'waiting' again after about 45 seconds — then call this again. Nothing is asked of the user, and no reason is needed.
Inputs: request (required).
wake_hostA
Turn the host on with Wake-on-LAN (it must support it and be set up for it).
Inputs: host (required), reason (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 47 tools
Most tools target a clearly distinct resource+action: power (guest/host/bulk/wake), snapshots (list/take/rollback/delete), backups (list/now/job CRUD/restore), guests (create/clone/details/usage/edit/delete). A few pairs are close — console_send vs console_type_password, guest_power vs bulk_power, backup_now vs run_backup_job — but the descriptions draw sharp lines (e.g. passwords only via the user's window, bulk = ordered batch as one task). No genuinely indistinguishable duplicates.
The dominant pattern is verb_noun in snake_case (list_guests, create_vm, delete_snapshot, edit_backup_job, grow_disk). Deviations are noun-prefixed families with a consistent noun (console_*, guest_*, host_*, list_backup_jobs) plus a couple like task_log; readability stays high and no camelCase mixing occurs.
47 tools is heavy and sits at the upper edge of what a single agent can hold in view, with several near-neighbours (backup job create/edit/delete/run, list_*, console_*) that drive the count up. The breadth is at least defensible for Proxmox management (VMs, containers, snapshots, backups, console, file transfer, host ops), so it is borderline rather than bloat.
Lifecycle coverage is strong: guest create/clone/edit/delete, snapshot take/list/rollback/delete, backup now/list/schedule/edit/delete/restore, plus console interaction, guest-agent commands, file transfer and host power. Remaining gaps are modest — no VM migration, no convert-to-template, no deletion of downloaded ISOs/templates, and disk handling is grow-only.
Maintenance
Related MCP Connectors
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables Claude to manage Proxmox VE infrastructure — VMs, LXC containers, snapshots, storage, and more.372MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to manage a Proxmox VE host through natural language, including guest lifecycle, snapshots, host status monitoring, and shell execution via a companion bridge.22 npm1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for managing Proxmox VE virtualization infrastructure, providing tools for VMs, containers, snapshots, storage, cluster nodes, and tasks. Compatible with Claude Desktop, Cline, and other MCP clients via natural language.MIT
- FlicenseNot gradedqualityDmaintenanceEnables managing a Proxmox cluster through natural language chat, including VM/container inventory, power control, configuration changes, cloning, snapshots, network/firewall visibility, and running commands or writing files inside guests.-