ProxmoxMCP Plus

ProxmoxMCP-Plus

[](https://buymeacoffee.com/rodaddy)

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.

Acknowledgments

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

New Features and Improvements

Major Enhancements

| Feature Category | Description | Tools | |-----------------|-------------|-------| | VM Lifecycle Management | Complete virtual machine creation, management, and deletion | create_vm, delete_vm | | Power Management | Control VM power states | start_vm, stop_vm, shutdown_vm, reset_vm | | Container Support | Full LXC container lifecycle management | get_containers, create_container, delete_container, start_container, stop_container, restart_container, update_container_resources | | Snapshot Management | Create and manage VM/container snapshots | list_snapshots, create_snapshot, delete_snapshot, rollback_snapshot | | Backup and Restore | Backup and restore VMs and containers | list_backups, create_backup, restore_backup, delete_backup | | ISO and Template Management | Manage installation media and templates | list_isos, list_templates, download_iso, delete_iso | | Monitoring | Cluster and resource monitoring | get_nodes, get_node_status, get_vms, get_storage, get_cluster_status | | OpenAPI Integration | REST API endpoints for external integration | 20+ API endpoints | | Security and Stability | Production-grade error handling and validation | Token-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

Installation

Prerequisites

• UV package manager (recommended)
• Python 3.9 or higher
• Git
• Access to a Proxmox server with API token credentials

Before starting, ensure you have:

• [ ] Proxmox server hostname or IP
• [ ] Proxmox API token (see [API Token Setup](#proxmox-api-token-setup))
• [ ] UV installed (pip install uv)

Option 1: Quick Install (Recommended)

1. Clone and set up environment:

```bash # 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 ```

1. Install dependencies:

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

1. Create configuration:

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

1. Edit proxmox-config/config.json:

``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 } } ``

Verifying Installation

1. Check Python environment:

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

1. Run the tests:

``bash pytest ``

1. Verify configuration:

```bash # Linux/macOS PROXMOXMCPCONFIG="proxmox-config/config.json" python -m proxmox_mcp.server

# Windows (PowerShell) $env:PROXMOXMCPCONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server ```

Configuration

Proxmox API Token Setup

1. Log into your Proxmox web interface
2. Navigate to Datacenter -> Permissions -> API Tokens
3. 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

Running the Server

Development Mode

For testing and development:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Run the server
python -m proxmox_mcp.server

MCP Transport Configuration

The MCP server supports multiple transport modes. Configure these in the mcp section of your proxmox-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.

OpenAPI Deployment (Production Ready)

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

Quick OpenAPI Start

# Install mcpo (MCP-to-OpenAPI proxy)
pip install mcpo

# Start OpenAPI service on port 8811
./start_openapi.sh

Docker Deployment

# 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

Access OpenAPI Service

Once deployed, access your service at:

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

Claude Desktop Integration

For Claude Desktop users, add this configuration to your MCP settings file:

Configuration file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Quick Setup:

1. Copy the example configuration:

```bash # macOS cp proxmox-config/claudedesktopconfig.example.json ~/Library/Application\ Support/Claude/claudedesktopconfig.json

# Linux cp proxmox-config/claudedesktopconfig.example.json ~/.config/Claude/claudedesktopconfig.json

# Windows (PowerShell) Copy-Item proxmox-config\claudedesktopconfig.example.json $env:APPDATA\Claude\claudedesktopconfig.json ```

1. Edit the file and replace the following values:

• /absolute/path/to/ProxmoxMCP-Plus - Full path to your installation
• your-proxmox-host - Your Proxmox server IP or hostname
• username@pve - Your Proxmox username
• token-name - Your API token name
• token-value - Your API token value

Configuration:

{
    "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"
            }
        }
    }
}

After configuration:

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

Cline Desktop Integration

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": []
        }
    }
}

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-default20240207amd64.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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rodaddy
• Source: rodaddy/ProxmoxMCP-Plus
• License: MIT

Install and usage instructions live in the source repository linked above.