Proxbase

Create, test and break real Proxmox VE clusters in QEMU/KVM on the local host.

Connector by virtbase · GitHub account verified by the MCP Registry

IndexedApache-2.0Local (stdio)★ 1

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/virtbase-proxbase

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

About

Create, test and break real Proxmox VE clusters in QEMU/KVM on the local host.

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 26, 2026.

Tools: 14 read · 8 write · 9 delete · 5 not yet classified
Secrets: None asked for
Install scripts: None found
Runs as: Docker image

Tools by what they do 36

Read from the source code; the running server may list different tools.

Read 14 · Look things up without changing anything.

cluster_env
cluster_list
cluster_plan
cluster_status
config_validate
file_get
host_check
image_list
pve_get
snapshot_list
snapshot_save
task_list

Show 2 more tools

task_log
token_list

Write 8 · Create, change, send or run things.

cluster_create
cluster_start
cluster_stop
cluster_ttl
fault_apply
file_put
node_add
token_create

Delete 9 · Delete, drop, revoke or wipe things.

cluster_destroy
cluster_gc
cluster_reset
fault_clear
image_prune
node_exec
node_remove
pve_call
token_delete

Not yet classified 5 · We could not tell from the name and description.

cluster_diagnose
cluster_wait
snapshot_delete
snapshot_restore
task_wait

Files it touches

/dev
/dev/kvm
/etc/dpkg/dpkg.cfg.d/proxbase-unsafe-io
/etc/passwd
/etc/proxbase-identity
/etc/pve/storage.cfg
/home/linuxbrew/.linuxbrew/Caskroom/proxbase/0.2.2/proxbase
/home/me
/home/me/.local/bin/proxbase
/home/me/go/bin/proxbase
/home/runner/work/_temp
/home/runner/work/_temp/proxbase-bin/proxbase
/opt/gobin
/opt/gobin/proxbase
/opt/homebrew/Caskroom/proxbase/0.2.2/proxbase
/proc/meminfo
/root/../etc/x
/root//a
/root/a
/root/a.yml
/sys/kernel/mm/ksm/run
/sys/module
/usr/local/Cellar/proxbase/0.2.2/bin/proxbase
/var/lib/pve-manager/apl-info/download.proxmox.com
/var/lib/vz/import
/var/lib/vz/template/cache
/var/log/pveam.log
Your home directory (~)

Tools (36)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

cluster_create
Create a Proxmox VE cluster (or resume a failed create of the same name). Without config, it creates 1 node with 4 vCPUs, 4G memory, a 32G ZFS root disk and one 32G data disk holding the ZFS pool "tank". Set nodes: 3 for a real cluster, storage: ceph for Ceph (3+ nodes). The create runs in the background on this host and survives this connection; the tool reports progress and returns when the cluster is ready, or with running=true after timeoutSeconds (then call cluster_wait). Cancelling the call cancels the create (re-run to resume). With snapshot="baseline" it saves a live snapshot when read…
cluster_destroy
Delete a cluster: kill its VMs and remove all its disks, snapshots and credentials. Also stops a create running in the background. Set confirm to the cluster name.
cluster_diagnose
Collect what explains a cluster problem, in one read-only call: the cluster status and, for every node, the quorum seen by it, failed systemd units, PVE tasks that failed, error log lines of corosync, pmxcfs (pve-cluster), pveproxy, pvedaemon, pvestatd, HA and Ceph from the last sinceMinutes, the clock offset, and ceph health detail. For nodes that are not running it returns the end of their serial console. Also lists the log files on this host.
cluster_env
Return what API and SSH clients need: API endpoint, API token (proxbase@pve!api, full privileges), the cluster CA certificate (PEM and path), SSH user, key path and ports per node. Root password only if includeRootPassword is set.
cluster_gc
Delete every expired cluster on this host (see ttlMinutes of cluster_create and cluster_ttl), with its disks and snapshots; clusters with a running job are left. dryRun only lists them.
cluster_list
List all proxbase clusters on this host with phase and running nodes.
cluster_plan
Work out what cluster_create would set up, without creating anything: nodes with IPs and ports (a new cluster takes the first free port range), the memory and disk of all nodes, whether the ISO is cached, the host's free memory and disk, warnings, and the resolved cluster file. Takes the parameters of cluster_create.
cluster_reset
Return a cluster to a snapshot in one call (default "baseline"): power the nodes off, restore the snapshot and start the cluster. A live snapshot resumes with its memory in seconds; a disk snapshot boots the nodes. Changes since the snapshot are lost. cluster_create with snapshot="baseline" saves one when the cluster is ready; snapshot_save saves one at any time.
cluster_start
Boot a stopped cluster and wait for quorum, the API and storage. Also boots nodes killed by fault_apply kill. If the call limit (50 s for clients that cancel tool calls after a minute) passes first, it returns healthy=false with what is pending while the nodes keep booting.
cluster_status
Show a cluster: phase, quorum, nodes (running/online, IP, web UI URL, SSH port), Ceph health, active faults, and the progress of a create running in the background. healthy=true means ready, quorate, all nodes online and Ceph HEALTH_OK.
cluster_stop
Shut all nodes of a cluster down (cleanly, then hard after the timeout). Disks are kept; cluster_start boots it again. Clears all faults.
cluster_ttl
Set how long a cluster may live: it expires minutes from now (0: never). cluster_gc deletes expired clusters; set a lifetime on clusters you create so that forgotten ones are cleaned up.
cluster_wait
Wait for the background job of a cluster (after cluster_create, node_add or node_remove returned running=true), reporting its progress. Returns running=false with the status when it finished, or running=true again after timeoutSeconds.
config_validate
Check a cluster file (YAML) without creating anything; returns errors, warnings and the file with all defaults. The schema is the resource https://proxbase.virtbase.com/schema/v1alpha1/cluster.json.
fault_apply
Inject a failure into a running cluster to test HA, fencing, Ceph or applications: kill, freeze, thaw, link-down, link-up, partition or degrade. fault_clear undoes them.

Show 21 more tools

fault_clear
Undo all injected faults (thaw, plug cables in, heal partitions and degradations). Killed nodes need cluster_start.
file_get
Read a file of a node: text as content, other data as contentBase64; at most maxBytes (default 256 KiB, max 4 MiB), truncated=true if the file is longer.
file_put
Write a file on a node as root, e.g. a config, script or test fixture: text in content, or binary data in contentBase64 (at most 4 MiB). The file is replaced atomically; missing directories are created. Files in /etc/pve (the cluster file system, shared by all nodes) get its fixed permissions.
host_check
Check whether this host can run clusters: KVM, nested virtualization, QEMU, free memory, KSM, disk space, free ports and path lengths (as proxbase doctor).
image_list
List the cached base images (golden images) with the clusters that use them.
image_prune
Delete the base images no cluster uses (dryRun only lists them). The next create with a deleted image builds it again.
node_add
Add nodes to a ready cluster: install (or clone) them, join them and set up ZFS or Ceph as configured. Runs in the background like cluster_create; returns when done or with running=true (then call cluster_wait). Cancelling the call stops it; cluster_create with the cluster's name finishes an interrupted add.
node_exec
Run a shell command as root on a running node over SSH and return stdout, stderr and the exit code. Use it for pvesh, qm, pct, pvecm, ceph and the like. Non-interactive; output is capped at 64 KiB per stream.
node_remove
Remove a node from a cluster: drain and destroy its Ceph daemons, take it out of the cluster and delete its VM and disks. Refuses with guests on the node or Ceph pools that would be left degraded unless force is set. Runs in the background like cluster_create. Set confirm to the node name.
pve_call
Change something through the Proxmox VE API of a cluster with its API token: POST, PUT or DELETE a path with params, e.g. POST /nodes/pve1/qemu {"vmid": 100, "memory": 2048} or POST /nodes/pve1/qemu/100/status/start. If the call starts a task (returns a UPID), waits for it and returns its exit status and log; a failed task is an error.
pve_get
Read from the Proxmox VE API of a cluster with its API token (proxbase@pve!api) and return the response data as JSON. Paths are those of pvesh and the API viewer, e.g. /cluster/resources, /cluster/status, /nodes/pve1/qemu, /nodes/pve1/storage, /nodes/pve1/tasks (recent tasks) or /nodes/pve1/tasks/<upid>/log.
snapshot_delete
Delete a snapshot of a cluster.
snapshot_list
List the snapshots of a cluster.
snapshot_restore
Reset all disks of a stopped cluster to a snapshot (call cluster_stop first). Changes since the snapshot are lost. After a disk snapshot call cluster_start; a live snapshot starts the cluster in its saved state by itself.
snapshot_save
Snapshot all disks of a stopped cluster (call cluster_stop first), or with live=true the running cluster including its memory. Restoring is much faster than creating again.
task_list
List the Proxmox VE tasks of a cluster, newest first: VM and container operations, migrations, backups, storage and Ceph jobs. Reads every node, or one. Filter by errorsOnly, running, type (e.g. qmstart, qmigrate, vzdump), vmid and sinceMinutes. task_log shows a task's log, task_wait waits for one to end.
task_log
Return the status and the end of the log of a Proxmox VE task, by its UPID (from task_list, pve_call or an error).
task_wait
Wait for a Proxmox VE task (UPID) to end and return its exit status and the end of its log; a failed task is an error. Use it for tasks that pve_call or task_list reported as running.
token_create
Create an API token that may only do what a role allows on a path, to test code with least privilege or check that an operation is refused: e.g. role PVEAuditor on /, PVEVMAdmin on /vms/100, PVEDatastoreUser on /storage/tank. Replaces a token of the same name. cluster_env with token returns the endpoint and CA with it.
token_delete
Delete a scoped API token and its grant. The main token proxbase@pve!api cannot be deleted.
token_list
List the scoped API tokens of a cluster with their role and path (without secrets).

Signals

Stars: 1
Forks: 0
Open issues: 1
Last commit: Oct 23, 2026 (5 days ago)
Last release: Oct 23, 2026 (5 days ago)

From GitHub (fetched Oct 24, 2026).

Details

Registry name: io.github.virtbase/proxbase
Version: 0.4.0
Auth: No auth
Packages: oci ghcr.io/virtbase/proxbase:0.4.0
License: Apache-2.0
Repository: github.com/virtbase/proxbase
Website: github.com/virtbase/proxbase/blob/main/docs/mcp.md
First seen: Oct 24, 2026
Last checked: Oct 24, 2026
Source: Official MCP Registry github-graphql

Cite this page

Proxbase MCP server. Agent Mart. https://agentmart.dev/connectors/virtbase-proxbase (last updated 2026-10-24)