Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault

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

CapabilityDetails
tools
{
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

B3.2/5.0

Scored across 47 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness4/5

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

ActivityActive
ResponsivenessNo recent community issues