proxmox-mcp
Control Proxmox VE VMs via MCP and OpenAPI
table of contents
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