Labsco
rodaddy logo

ProxmoxMCP-Plus

ā˜… 7

from rodaddy

roxmox VE management MCP server with full OpenAPI integration for controlling VMs, containers, and cluster resources

šŸ”„šŸ”„šŸ”„šŸ”„āœ“ VerifiedAccount requiredAdvanced setup
#automation#devops#git#maps#security#monitoring

ProxmoxMCP-Plus

An enhanced Python-based Model Context Protocol (MCP) server for interacting with Proxmox virtualization platforms. This project extends canvrno/ProxmoxMCP with additional features including complete OpenAPI integration and expanded virtualization management capabilities.

New Features and Improvements

Major Enhancements

Feature CategoryDescriptionTools
VM Lifecycle ManagementComplete virtual machine creation, management, and deletioncreate_vm, delete_vm
Power ManagementControl VM power statesstart_vm, stop_vm, shutdown_vm, reset_vm
Container SupportFull LXC container lifecycle managementget_containers, create_container, delete_container, start_container, stop_container, restart_container, update_container_resources
Snapshot ManagementCreate and manage VM/container snapshotslist_snapshots, create_snapshot, delete_snapshot, rollback_snapshot
Backup and RestoreBackup and restore VMs and containerslist_backups, create_backup, restore_backup, delete_backup
ISO and Template ManagementManage installation media and templateslist_isos, list_templates, download_iso, delete_iso
MonitoringCluster and resource monitoringget_nodes, get_node_status, get_vms, get_storage, get_cluster_status
OpenAPI IntegrationREST API endpoints for external integration20+ API endpoints
Security and StabilityProduction-grade error handling and validationToken-based authentication, comprehensive logging

Built With

  • Proxmoxer - Python wrapper for Proxmox API
  • MCP SDK - Model Context Protocol SDK
  • Pydantic - Data validation using Python type annotations

Features

  • Full integration with Cline and Open WebUI
  • Built with the official MCP SDK
  • Secure token-based authentication with Proxmox
  • Complete VM lifecycle management (create, start, stop, reset, shutdown, delete)
  • VM console command execution
  • LXC container management support
  • Intelligent storage type detection (LVM/file-based)
  • Configurable logging system
  • Type-safe implementation with Pydantic
  • Rich output formatting with customizable themes
  • OpenAPI REST endpoints for integration
  • 20+ fully functional API endpoints
  • Complete snapshot management (create, delete, rollback)
  • Backup and restore capabilities
  • ISO and template management

Available Tools & API Endpoints

The server provides comprehensive MCP tools and corresponding REST API endpoints:

VM Management Tools

create_vm

Create a new virtual machine with specified resources.

Parameters:

  • node (string, required): Name of the node
  • vmid (string, required): ID for the new VM
  • name (string, required): Name for the VM
  • cpus (integer, required): Number of CPU cores (1-32)
  • memory (integer, required): Memory in MB (512-131072)
  • disk_size (integer, required): Disk size in GB (5-1000)
  • storage (string, optional): Storage pool name
  • ostype (string, optional): OS type (default: l26)

API Endpoint:

POST /create_vm
Content-Type: application/json

{
    "node": "pve",
    "vmid": "200",
    "name": "my-vm",
    "cpus": 1,
    "memory": 2048,
    "disk_size": 10
}

Example Response:

VM 200 created successfully.

VM Configuration:
  - Name: my-vm
  - Node: pve
  - VM ID: 200
  - CPU Cores: 1
  - Memory: 2048 MB (2.0 GB)
  - Disk: 10 GB (local-lvm, raw format)
  - Storage Type: lvmthin
  - Network: virtio (bridge=vmbr0)
  - QEMU Agent: Enabled

Task ID: UPID:pve:001AB729:0442E853:682FF380:qmcreate:200:root@pam!mcp

VM Power Management

start_vm: Start a virtual machine

POST /start_vm
{"node": "pve", "vmid": "200"}

stop_vm: Force stop a virtual machine

POST /stop_vm
{"node": "pve", "vmid": "200"}

shutdown_vm: Gracefully shutdown a virtual machine

POST /shutdown_vm
{"node": "pve", "vmid": "200"}

reset_vm: Reset (restart) a virtual machine

POST /reset_vm
{"node": "pve", "vmid": "200"}

delete_vm: Completely delete a virtual machine

POST /delete_vm
{"node": "pve", "vmid": "200", "force": false}

Snapshot Management Tools

list_snapshots

List all snapshots for a VM or container.

Parameters:

  • node (string, required): Host node name (e.g. 'pve')
  • vmid (string, required): VM or container ID (e.g. '100')
  • vm_type (string, optional): Type - 'qemu' for VMs, 'lxc' for containers (default: 'qemu')

API Endpoint: POST /list_snapshots

Example:

POST /list_snapshots
{"node": "pve", "vmid": "100", "vm_type": "qemu"}

create_snapshot

Create a snapshot of a VM or container.

Parameters:

  • node (string, required): Host node name
  • vmid (string, required): VM or container ID
  • snapname (string, required): Snapshot name (no spaces, e.g. 'before-update')
  • description (string, optional): Description for the snapshot
  • vmstate (boolean, optional): Include memory state (VMs only, default: false)
  • vm_type (string, optional): Type - 'qemu' or 'lxc' (default: 'qemu')

API Endpoint:

POST /create_snapshot
Content-Type: application/json

{
    "node": "pve",
    "vmid": "100",
    "snapname": "pre-upgrade",
    "description": "Before system upgrade",
    "vmstate": true
}

delete_snapshot

Delete a snapshot.

Parameters:

  • node (string, required): Host node name
  • vmid (string, required): VM or container ID
  • snapname (string, required): Snapshot name to delete
  • vm_type (string, optional): Type - 'qemu' or 'lxc' (default: 'qemu')

API Endpoint:

POST /delete_snapshot
{"node": "pve", "vmid": "100", "snapname": "old-snapshot"}

rollback_snapshot

Rollback VM/container to a previous snapshot.

WARNING: This will stop the VM/container and restore to the snapshot state!

Parameters:

  • node (string, required): Host node name
  • vmid (string, required): VM or container ID
  • snapname (string, required): Snapshot name to restore
  • vm_type (string, optional): Type - 'qemu' or 'lxc' (default: 'qemu')

API Endpoint:

POST /rollback_snapshot
{"node": "pve", "vmid": "100", "snapname": "before-update"}

Container Management Tools

get_containers

List all LXC containers across the cluster.

API Endpoint: POST /get_containers

Example Response:

Containers

nginx-server (ID: 200)
  - Status: RUNNING
  - Node: pve
  - CPU Cores: 2
  - Memory: 1.5 GB / 2.0 GB (75.0%)

create_container

Create a new LXC container with specified configuration.

Parameters:

  • node (string, required): Host node name (e.g. 'pve')
  • vmid (string, required): Container ID number (e.g. '200')
  • ostemplate (string, required): OS template path (e.g. 'local:vztmpl/alpine-3.19-default_20240207_amd64.tar.xz')
  • hostname (string, optional): Container hostname (defaults to 'ct-{vmid}')
  • cores (integer, optional): Number of CPU cores (default: 1)
  • memory (integer, optional): Memory size in MiB (default: 512)
  • swap (integer, optional): Swap size in MiB (default: 512)
  • disk_size (integer, optional): Root disk size in GB (default: 8)
  • storage (string, optional): Storage pool for rootfs (auto-detects if not specified)
  • password (string, optional): Root password
  • ssh_public_keys (string, optional): SSH public keys for root user
  • network_bridge (string, optional): Network bridge name (default: 'vmbr0')
  • start_after_create (boolean, optional): Start container after creation (default: false)
  • unprivileged (boolean, optional): Create unprivileged container (default: true)

API Endpoint:

POST /create_container
Content-Type: application/json

{
    "node": "pve",
    "vmid": "200",
    "ostemplate": "local:vztmpl/alpine-3.19-default_20240207_amd64.tar.xz",
    "hostname": "my-container",
    "cores": 2,
    "memory": 1024,
    "disk_size": 10
}

delete_container

Delete/remove an LXC container completely.

WARNING: This operation permanently deletes the container and all its data!

Parameters:

  • selector (string, required): Container selector - '123' | 'pve1:123' | 'pve1/name' | 'name'
  • force (boolean, optional): Force deletion even if container is running (default: false)

API Endpoint:

POST /delete_container
Content-Type: application/json

{
    "selector": "200",
    "force": false
}

Backup and Restore Tools

list_backups

List available backups across the cluster.

Parameters:

  • node (string, optional): Filter by node
  • storage (string, optional): Filter by storage pool
  • vmid (string, optional): Filter by VM/container ID

API Endpoint: POST /list_backups

Example:

POST /list_backups
{"node": "pve", "storage": "backup-storage"}

create_backup

Create a backup of a VM or container.

Parameters:

  • node (string, required): Node where VM/container runs
  • vmid (string, required): VM or container ID to backup
  • storage (string, required): Target backup storage
  • compress (string, optional): Compression - '0', 'gzip', 'lz4', 'zstd' (default: 'zstd')
  • mode (string, optional): Backup mode - 'snapshot', 'suspend', 'stop' (default: 'snapshot')
  • notes (string, optional): Notes/description for the backup

API Endpoint:

POST /create_backup
Content-Type: application/json

{
    "node": "pve",
    "vmid": "100",
    "storage": "backup-storage",
    "compress": "zstd",
    "mode": "snapshot",
    "notes": "Weekly backup"
}

restore_backup

Restore a VM or container from a backup.

Parameters:

  • node (string, required): Target node for restore
  • archive (string, required): Backup volume ID (from list_backups output)
  • vmid (string, required): New VM/container ID for the restored machine
  • storage (string, optional): Target storage for disks (uses original if not specified)
  • unique (boolean, optional): Generate unique MAC addresses (default: true)

API Endpoint:

POST /restore_backup
Content-Type: application/json

{
    "node": "pve",
    "archive": "backup:backup/vzdump-qemu-100-2024_01_15.vma.zst",
    "vmid": "200",
    "unique": true
}

delete_backup

Delete a backup file from storage.

WARNING: This permanently deletes the backup!

Parameters:

  • node (string, required): Node name
  • storage (string, required): Storage pool name
  • volid (string, required): Backup volume ID to delete

API Endpoint:

POST /delete_backup
{
    "node": "pve",
    "storage": "backup-storage",
    "volid": "backup:backup/vzdump-qemu-100-2024_01_15.vma.zst"
}

ISO and Template Management Tools

list_isos

List available ISO images across the cluster.

Parameters:

  • node (string, optional): Filter by node
  • storage (string, optional): Filter by storage pool

API Endpoint: POST /list_isos

Returns: List of ISOs with filename, size, and storage location.

list_templates

List available OS templates for container creation.

Parameters:

  • node (string, optional): Filter by node
  • storage (string, optional): Filter by storage pool

API Endpoint: POST /list_templates

Returns: List of templates (vztmpl) with name, size, and storage. Use the returned Volume ID with create_container's ostemplate parameter.

download_iso

Download an ISO image from a URL to Proxmox storage.

Parameters:

  • node (string, required): Target node name
  • storage (string, required): Target storage pool (must support ISO content)
  • url (string, required): URL to download from
  • filename (string, required): Target filename (e.g. 'ubuntu-22.04-live-server-amd64.iso')
  • checksum (string, optional): Checksum for verification
  • checksum_algorithm (string, optional): Algorithm - 'sha256', 'sha512', 'md5' (default: 'sha256')

API Endpoint:

POST /download_iso
Content-Type: application/json

{
    "node": "pve",
    "storage": "local",
    "url": "https://releases.ubuntu.com/22.04/ubuntu-22.04-live-server-amd64.iso",
    "filename": "ubuntu-22.04-live-server-amd64.iso",
    "checksum": "a1b2c3..."
}

delete_iso

Delete an ISO or template from storage.

Parameters:

  • node (string, required): Node name
  • storage (string, required): Storage pool name
  • filename (string, required): ISO/template filename to delete

API Endpoint:

POST /delete_iso
{
    "node": "pve",
    "storage": "local",
    "filename": "old-distro.iso"
}

Monitoring Tools

get_nodes

Lists all nodes in the Proxmox cluster.

API Endpoint: POST /get_nodes

Example Response:

Proxmox Nodes

pve-compute-01
  - Status: ONLINE
  - Uptime: 156d 12h
  - CPU Cores: 64
  - Memory: 186.5 GB / 512.0 GB (36.4%)

get_node_status

Get detailed status of a specific node.

Parameters:

  • node (string, required): Name of the node

API Endpoint: POST /get_node_status

get_vms

List all VMs across the cluster.

API Endpoint: POST /get_vms

get_storage

List available storage pools.

API Endpoint: POST /get_storage

get_cluster_status

Get overall cluster status and health.

API Endpoint: POST /get_cluster_status

execute_vm_command

Execute a command in a VM's console using QEMU Guest Agent.

Parameters:

  • node (string, required): Name of the node where VM is running
  • vmid (string, required): ID of the VM
  • command (string, required): Command to execute

API Endpoint: POST /execute_vm_command

Requirements:

  • VM must be running
  • QEMU Guest Agent must be installed and running in the VM

Open WebUI Integration

Configure Open WebUI

  1. Access your Open WebUI instance
  2. Navigate to Settings ā†’ Connections ā†’ OpenAPI
  3. Add new API configuration:
{
  "name": "Proxmox MCP API Plus",
  "base_url": "http://your-server:8811",
  "api_key": "",
  "description": "Enhanced Proxmox Virtualization Management API"
}

Natural Language VM Creation

The system supports natural language VM creation requests through AI assistants. Example requests:

  • "Can you create a VM with 1 cpu core and 2 GB ram with 10GB of storage disk"
  • "Create a new VM for testing with minimal resources"
  • "I need a development server with 4 cores and 8GB RAM"

The AI assistant will automatically call the appropriate APIs and provide detailed feedback.

Storage Type Support

Intelligent Storage Detection

ProxmoxMCP Plus automatically detects storage types and selects appropriate disk formats:

LVM Storage (local-lvm, vm-storage)

  • Format: raw
  • High performance
  • Note: No cloud-init image support

File-based Storage (local, NFS, CIFS)

  • Format: qcow2
  • Cloud-init support
  • Flexible snapshot capabilities

Project Structure

ProxmoxMCP-Plus/
ā”œā”€ā”€ src/                          # Source code
ā”‚   ā””ā”€ā”€ proxmox_mcp/
ā”‚       ā”œā”€ā”€ server.py             # Main MCP server implementation
ā”‚       ā”œā”€ā”€ config/               # Configuration handling
ā”‚       ā”œā”€ā”€ core/                 # Core functionality
ā”‚       ā”œā”€ā”€ formatting/           # Output formatting and themes
ā”‚       ā”œā”€ā”€ tools/                # Tool implementations
ā”‚       ā”‚   ā”œā”€ā”€ vm.py             # VM management
ā”‚       ā”‚   ā”œā”€ā”€ container.py      # Container management
ā”‚       ā”‚   ā””ā”€ā”€ console/          # VM console operations
ā”‚       ā””ā”€ā”€ utils/                # Utilities (auth, logging)
ā”‚
ā”œā”€ā”€ tests/                        # Unit test suite
ā”œā”€ā”€ test_scripts/                 # Integration tests & demos
ā”‚   ā”œā”€ā”€ README.md                 # Test documentation
ā”‚   ā”œā”€ā”€ test_vm_power.py          # VM power management tests
ā”‚   ā”œā”€ā”€ test_vm_start.py          # VM startup tests
ā”‚   ā”œā”€ā”€ test_create_vm.py         # VM creation tests
ā”‚   ā””ā”€ā”€ test_openapi.py           # OpenAPI service tests
ā”‚
ā”œā”€ā”€ proxmox-config/               # Configuration files
ā”‚   ā””ā”€ā”€ config.json               # Server configuration
ā”‚
ā”œā”€ā”€ Configuration Files
ā”‚   ā”œā”€ā”€ pyproject.toml            # Project metadata
ā”‚   ā”œā”€ā”€ docker-compose.yml        # Docker orchestration
ā”‚   ā”œā”€ā”€ Dockerfile                # Docker image definition
ā”‚   ā””ā”€ā”€ requirements.in           # Dependencies
ā”‚
ā”œā”€ā”€ Scripts
ā”‚   ā”œā”€ā”€ start_server.sh           # MCP server launcher
ā”‚   ā””ā”€ā”€ start_openapi.sh          # OpenAPI service launcher
ā”‚
ā””ā”€ā”€ Documentation
    ā”œā”€ā”€ README.md                 # This file
    ā”œā”€ā”€ VM_CREATION_GUIDE.md      # VM creation guide
    ā”œā”€ā”€ OPENAPI_DEPLOYMENT.md     # OpenAPI deployment
    ā””ā”€ā”€ LICENSE                   # MIT License

Testing

Run Unit Tests

pytest

Run Integration Tests

cd test_scripts

# Test VM power management
python test_vm_power.py

# Test VM creation
python test_create_vm.py

# Test OpenAPI service
python test_openapi.py

API Testing with curl

# Test node listing
curl -X POST "http://your-server:8811/get_nodes" \
  -H "Content-Type: application/json" \
  -d "{}"

# Test VM creation
curl -X POST "http://your-server:8811/create_vm" \
  -H "Content-Type: application/json" \
  -d '{
    "node": "pve",
    "vmid": "300",
    "name": "test-vm",
    "cpus": 1,
    "memory": 2048,
    "disk_size": 10
  }'

Production Security

API Key Authentication

Set up secure API access:

export PROXMOX_API_KEY="your-secure-api-key"
export PROXMOX_MCP_CONFIG="/app/proxmox-config/config.json"

Nginx Reverse Proxy

Example nginx configuration:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:8811;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Development

After activating your virtual environment:

  • Run tests: pytest
  • Format code: black .
  • Type checking: mypy .
  • Lint: ruff .

Special Thanks

  • @canvrno for the foundational project ProxmoxMCP
  • Thanks to the Proxmox community for providing the powerful virtualization platform
  • Thanks to all contributors and users for their support

ProxmoxMCP Plus with OpenAPI integration is ready for production deployment.