Skip to main content
Glama
claude-proxmox-controller

claude-proxmox-controller

Claude Proxmox Controller

Tests

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 .deb from 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.deb
  • Ubuntu / 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-controller

    The 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.sh

The 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 tools
backup_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_jobA
Destructive

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_backupB
Destructive

Delete a backup (not a protected one).

Inputs: host (required), volid (required), reason (required).

delete_backup_jobA
Destructive

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_guestA
Destructive

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_snapshotD
Destructive

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_jobA
Destructive

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_detailsB
Read-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_usageA
Read-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_powerB
Destructive

Shut down or reboot the host itself (its guests are shut down first).

Inputs: host (required), action (required), reason (required), node.

host_statusC
Read-onlyIdempotent

A host's nodes: CPU, memory, system disk, uptime, load, and storage use.

Inputs: host (required).

list_backup_jobsA
Read-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_backupsA
Read-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_guestsB
Read-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_hostsA
Read-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_mediaC
Read-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_snapshotsC
Read-onlyIdempotent

A guest's snapshots.

Inputs: host (required), vmid (required).

list_tasksB
Read-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_backupA
Destructive

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_snapshotA
Destructive

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_taskB
Destructive

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_logC
Read-onlyIdempotent

A task's log (a backup's progress, an error).

Inputs: host (required), upid (required), start.

wait_for_requestA
Read-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

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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