ProxmoxMCP-Plus

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

This project is built upon the open-source projectProxmoxMCPby@canvrno.

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

- Proxmox server hostname or IP
- Proxmox API token (seeAPI Token Setup)
- UV installed (pip install uv)

# Clone repository git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git cd ProxmoxMCP-Plus # Create and activate virtual environment uv venv source .venv/bin/activate # Linux/macOS # OR .\.venv\Scripts\Activate.ps1 # Windows

# Install with development dependencies uv pip install -e ".[dev]"

# Create config directory and copy template mkdir -p proxmox-config cp proxmox-config/config.example.json proxmox-config/config.json

{ "proxmox": { "host": "PROXMOX_HOST", # Required: Your Proxmox server address "port": 8006, # Optional: Default is 8006 "verify_ssl": false, # Optional: Set false for self-signed certs "service": "PVE" # Optional: Default is PVE }, "auth": { "user": "USER@pve", # Required: Your Proxmox username "token_name": "TOKEN_NAME", # Required: API token ID "token_value": "TOKEN_VALUE" # Required: API token value }, "logging": { "level": "INFO", # Optional: DEBUG for more detail "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", "file": "proxmox_mcp.log" # Optional: Log to file }, "mcp": { "host": "127.0.0.1", # Optional: Host for SSE/STREAMABLE transports "port": 8000, # Optional: Port for SSE/STREAMABLE transports "transport": "STDIO" # Optional: STDIO, SSE, or STREAMABLE } }

python -c "import proxmox_mcp; print('Installation OK')"

# Linux/macOS PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server # Windows (PowerShell) $env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server

- Log into your Proxmox web interface
- Navigate to Datacenter -> Permissions -> API Tokens
- Create a new API token:

- Select a user (e.g., root@pam)
- Enter a token ID (e.g., "mcp-token")
- Uncheck "Privilege Separation" if you want full access
- Save and copy both the token ID and secret

# Activate virtual environment first source .venv/bin/activate # Linux/macOS # OR .\.venv\Scripts\Activate.ps1 # Windows # Run the server python -m proxmox_mcp.server

The MCP server supports multiple transport modes. Configure these in themcpsection of yourproxmox-config/config.json:

- STDIO: Default. Run over stdio for MCP clients like Claude Desktop/Cline.
- SSE: Serve MCP over Server-Sent Events (SSE).
- STREAMABLE: Serve MCP over streamable HTTP.

Deploy ProxmoxMCP Plus as standard OpenAPI REST endpoints for integration with Open WebUI and other applications.

# Install mcpo (MCP-to-OpenAPI proxy) pip install mcpo # Start OpenAPI service on port 8811 ./start_openapi.sh

# Build and run with Docker docker build -t proxmox-mcp-api . docker run -d --name proxmox-mcp-api -p 8811:8811 \ -v $(pwd)/proxmox-config:/app/proxmox-config proxmox-mcp-api # Or use Docker Compose docker-compose up -d

- API Documentation:http://your-server:8811/docs
- OpenAPI Specification:http://your-server:8811/openapi.json
- Health Check:http://your-server:8811/health

# macOS cp proxmox-config/claude_desktop_config.example.json ~/Library/Application\ Support/Claude/claude_desktop_config.json # Linux cp proxmox-config/claude_desktop_config.example.json ~/.config/Claude/claude_desktop_config.json # Windows (PowerShell) Copy-Item proxmox-config\claude_desktop_config.example.json $env:APPDATA\Claude\claude_desktop_config.json

{ "mcpServers": { "ProxmoxMCP-Plus": { "command": "/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python", "args": ["-m", "proxmox_mcp.server"], "env": { "PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src", "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json", "PROXMOX_HOST": "your-proxmox-host", "PROXMOX_USER": "username@pve", "PROXMOX_TOKEN_NAME": "token-name", "PROXMOX_TOKEN_VALUE": "token-value", "PROXMOX_PORT": "8006", "PROXMOX_VERIFY_SSL": "false", "PROXMOX_SERVICE": "PVE", "LOG_LEVEL": "DEBUG" } } } }

- Restart Claude Desktop
- The ProxmoxMCP-Plus tools will be available in your conversations
- You can now manage your Proxmox infrastructure through Claude Desktop!

For Cline users, add this configuration to your MCP settings file (typically at~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{ "mcpServers": { "ProxmoxMCP-Plus": { "command": "/absolute/path/to/ProxmoxMCP-Plus/.venv/bin/python", "args": ["-m", "proxmox_mcp.server"], "cwd": "/absolute/path/to/ProxmoxMCP-Plus", "env": { "PYTHONPATH": "/absolute/path/to/ProxmoxMCP-Plus/src", "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP-Plus/proxmox-config/config.json", "PROXMOX_HOST": "your-proxmox-host", "PROXMOX_USER": "username@pve", "PROXMOX_TOKEN_NAME": "token-name", "PROXMOX_TOKEN_VALUE": "token-value", "PROXMOX_PORT": "8006", "PROXMOX_VERIFY_SSL": "false", "PROXMOX_SERVICE": "PVE", "LOG_LEVEL": "DEBUG" }, "disabled": false, "autoApprove": [] } } }

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

Create a new virtual machine with specified resources.

- 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)

POST /create_vm Content-Type: application/json { "node": "pve", "vmid": "200", "name": "my-vm", "cpus": 1, "memory": 2048, "disk_size": 10 }

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

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

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}

List all snapshots for a VM or container.

- 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')

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

- 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')

POST /create_snapshot Content-Type: application/json { "node": "pve", "vmid": "100", "snapname": "pre-upgrade", "description": "Before system upgrade", "vmstate": true }

- 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')

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

Rollback VM/container to a previous snapshot.

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

- 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')

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

List all LXC containers across the cluster.

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

Create a new LXC container with specified configuration.

- 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)

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/remove an LXC container completely.

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

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

POST /delete_container Content-Type: application/json { "selector": "200", "force": false }

List available backups across the cluster.

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

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

- 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

POST /create_backup Content-Type: application/json { "node": "pve", "vmid": "100", "storage": "backup-storage", "compress": "zstd", "mode": "snapshot", "notes": "Weekly backup" }

Restore a VM or container from a backup.

- 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)

POST /restore_backup Content-Type: application/json { "node": "pve", "archive": "backup:backup/vzdump-qemu-100-2024_01_15.vma.zst", "vmid": "200", "unique": true }

WARNING:This permanently deletes the backup!

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

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

List available ISO images across the cluster.

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

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

List available OS templates for container creation.

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

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