claude-proxmox-controller
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Proxmox Controller lets you manage the user's Proxmox VE hosts. Call list_hosts first: it gives each host's id and, per kind of request (read, power, change, destroy, host, console, commands, host_commands), whether it is off, ask or on. 'ask' means the user approves each request in a window of the app (it may take a while, and they may deny it); 'off' means it will be refused — tell the user instead of trying another way. Every request other than reading needs a short reason, shown to the user. Long Proxmox tasks come back as running: follow them with task_log. A request not done within about 45 seconds (the user has not answered its window yet, or its work goes on) comes back with status 'waiting' and an id: call wait_for_request with it until the answer comes — never send the request again, or it is asked or done twice. If a request ever fails with a timeout on your side, it may still have been approved and done: check (list_guests, list_tasks) before asking again. You never give or see a password: where one is needed (a new VM's user, a container's root, a console prompt) the user types it in the app's window.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_hostsA | 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. |
| host_statusC | A host's nodes: CPU, memory, system disk, uptime, load, and storage use. |
| list_guestsB | Every VM and container of a host: state, CPU, memory, disk, IP addresses, tags, start at boot and boot order, notes. |
| guest_detailsB | One guest's full Proxmox configuration, and for a VM the settings waiting for its next start. |
| list_snapshotsC | A guest's snapshots. |
| list_backupsA | A guest's backups, newest first — also of a guest deleted since, by its old ID. |
| list_backup_jobsA | 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. |
| list_tasksB | The host's recent tasks, newest first, with how they ended. |
| task_logC | A task's log (a backup's progress, an error). |
| guest_usageA | A guest's average and peak CPU, memory, network and disk use over the last hour, day, week or month. |
| list_install_mediaC | What new guests can be made from: ISO images, container templates, storages, network bridges and the next free VMID. |
| guest_powerA | Start, shut down (clean), stop (at once, like pulling the plug — only if shut down does not work) or reboot a guest. |
| 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. |
| wake_hostA | Turn the host on with Wake-on-LAN (it must support it and be set up for it). |
| 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. |
| grow_diskA | Make a guest's disk bigger (never smaller). |
| take_snapshotC | Take a snapshot of a guest. |
| backup_nowB | Back a guest up now (it keeps running in snapshot mode). |
| create_backup_jobA | 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-. |
| edit_backup_jobA | 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| clone_vmC | Copy a VM or a template as a new VM. |
| download_isoC | Have the host download an ISO image from a web address. |
| restore_backupA | 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. |
| delete_guestA | 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. |
| rollback_snapshotA | Roll a guest back to a snapshot (what came after it is lost). |
| delete_snapshotD | Delete a snapshot. |
| delete_backup_jobA | 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. |
| delete_backupB | Delete a backup (not a protected one). |
| stop_taskB | Stop a running task (one started through this connector). |
| host_powerB | Shut down or reboot the host itself (its guests are shut down first). |
| 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. |
| 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). |
| 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"]}]. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| wait_for_requestA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.