Proxmox

Control Proxmox VE VMs via MCP and OpenAPI

table of contents

• install
• usage
• api
• contributing
• license

install

pip install proxmox-mcp

usage

from proxmox_mcp import ProxmoxMCP

# initialize client
client = ProxmoxMCP(
    host="proxmox.example.com",
    user="root@pam",
    password="your_password"
)

# list all vms
vms = client.list_vms()
for vm in vms:
    print(f"{vm.vmid}: {vm.name} - {vm.status}")

# start a vm
client.start_vm(vmid=100)

# get vm status
status = client.get_vm_status(vmid=100)
print(f"VM 100 is {status}")

# create snapshot
client.create_snapshot(vmid=100, snapname="backup-2024")

# clone vm
client.clone_vm(vmid=100, newid=101, name="clone-vm")

api

Method	Description	Parameters
list_vms()	Get all VMs across all nodes	none
get_vm_status(vmid)	Get current VM status	vmid: int
start_vm(vmid)	Start a VM	vmid: int
stop_vm(vmid)	Stop a VM	vmid: int
restart_vm(vmid)	Restart a VM	vmid: int
shutdown_vm(vmid)	Graceful shutdown	vmid: int
create_snapshot(vmid, snapname)	Create VM snapshot	vmid: int, snapname: str
delete_snapshot(vmid, snapname)	Delete VM snapshot	vmid: int, snapname: str
clone_vm(vmid, newid, name)	Clone a VM	vmid: int, newid: int, name: str
get_vm_config(vmid)	Get VM configuration	vmid: int
update_vm_config(vmid, config)	Update VM settings	vmid: int, config: dict

MCP integration

The library exposes Proxmox operations through the Model Context Protocol, allowing AI assistants to manage VMs directly.

# mcp server mode
from proxmox_mcp.server import run_mcp_server

run_mcp_server(
    host="proxmox.example.com",
    user="root@pam",
    password="your_password",
    port=8080
)

OpenAPI schema

OpenAPI 3.0 spec available at /openapi.json when running in server mode. Import into tools like Postman or generate clients in other languages.

contributing

prs welcome. open an issue first for big changes.

license

MIT