Offers production-ready Docker deployment for the MCP server, with complete configuration for containerized operation including Docker Compose support.
Provides example configuration for NGINX reverse proxy setup to securely expose the MCP server in production environments.
Provides complete VM lifecycle management capabilities for Proxmox virtualization platforms, including creating, starting, stopping, resetting, shutting down, and deleting VMs. Also supports LXC container management, storage pool monitoring, cluster health checks, and VM console command execution.
ProxmoxMCP-Plus - Enhanced Proxmox MCP Server
An enhanced Python-based Model Context Protocol (MCP) server for interacting with Proxmox virtualization platforms. This project is built upon canvrno/ProxmoxMCP with numerous new features and improvements, providing complete OpenAPI integration and more powerful virtualization management capabilities.
Acknowledgments
This project is built upon the excellent open-source project ProxmoxMCP by @canvrno. Thanks to the original author for providing the foundational framework and creative inspiration!
🆕 New Features and Improvements
Major enhancements compared to the original version:
✨ Complete VM Lifecycle Management
Brand new
create_vm
tool - Support for creating virtual machines with custom configurationsNew
delete_vm
tool - Safe VM deletion (with force deletion option)Enhanced intelligent storage type detection (LVM/file-based)
🔧 Extended Power Management Features
start_vm
- Start virtual machinesstop_vm
- Force stop virtual machinesshutdown_vm
- Graceful shutdownreset_vm
- Restart virtual machines
🐳 New Container Support
get_containers
- List all LXC containers and their statusstart_container
- Start LXC containerstop_container
- Stop LXC containerrestart_container
- Restart LXC container (forcefully/gracefully)update_container_resources
- Adjust container CPU, memory, swap, or extend disk
📊 Enhanced Monitoring and Display
Improved storage pool status monitoring
More detailed cluster health status checks
Rich output formatting and themes
🌐 Complete OpenAPI Integration
11 complete REST API endpoints
Production-ready Docker deployment
Perfect Open WebUI integration
Natural language VM creation support
🛡️ Production-grade Security and Stability
Enhanced error handling mechanisms
Comprehensive parameter validation
Production-level logging
Complete unit test coverage
Built With
Cline - Autonomous coding agent - Go faster with Cline
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
📡 11 fully functional API endpoints
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)
UV installed (
pip install uv
)
Option 1: Quick Install (Recommended)
Clone and set up environment:
# 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 # WindowsInstall dependencies:
# Install with development dependencies uv pip install -e ".[dev]"Create configuration:
# Create config directory and copy template mkdir -p proxmox-config cp proxmox-config/config.example.json proxmox-config/config.jsonEdit
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 } }
Verifying Installation
Check Python environment:
python -c "import proxmox_mcp; print('Installation OK')"Run the tests:
pytestVerify configuration:
# 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
Configuration
Proxmox API Token Setup
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
Running the Server
Development Mode
For testing and development:
OpenAPI Deployment (Production Ready)
Deploy ProxmoxMCP Plus as standard OpenAPI REST endpoints for integration with Open WebUI and other applications.
Quick OpenAPI Start
Docker Deployment
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
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
):
Available Tools & API Endpoints
The server provides 11 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 nodevmid
(string, required): ID for the new VMname
(string, required): Name for the VMcpus
(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 nameostype
(string, optional): OS type (default: l26)
API Endpoint:
Example Response:
VM Power Management 🆕
start_vm: Start a virtual machine
stop_vm: Force stop a virtual machine
shutdown_vm: Gracefully shutdown a virtual machine
reset_vm: Reset (restart) a virtual machine
delete_vm 🆕: Completely delete a virtual machine
🆕 Container Management Tools
get_containers 🆕
List all LXC containers across the cluster.
API Endpoint: POST /get_containers
Example Response:
Monitoring Tools
get_nodes
Lists all nodes in the Proxmox cluster.
API Endpoint: POST /get_nodes
Example Response:
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 runningvmid
(string, required): ID of the VMcommand
(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
Access your Open WebUI instance
Navigate to Settings → Connections → OpenAPI
Add new API configuration:
Natural Language VM Creation
Users can now request VMs using natural language:
"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
⚠️ No cloud-init image support
File-based Storage (local, NFS, CIFS)
✅ Format:
qcow2
✅ Cloud-init support
✅ Flexible snapshot capabilities
Project Structure
Testing
Run Unit Tests
Run Integration Tests
API Testing with curl
Production Security
API Key Authentication
Set up secure API access:
Nginx Reverse Proxy
Example nginx configuration:
Troubleshooting
Common Issues
Port already in use
netstat -tlnp | grep 8811 # Change port if needed mcpo --port 8812 -- ./start_server.shConfiguration errors
# Verify config file cat proxmox-config/config.jsonConnection issues
# Test Proxmox connectivity curl -k https://your-proxmox:8006/api2/json/version
View Logs
Deployment Status
✅ Feature Completion: 100%
VM Creation (user requirement: 1 CPU + 2GB RAM + 10GB storage) 🆕
VM Power Management (start VPN-Server ID:101) 🆕
VM Deletion Feature 🆕
Container Management (LXC) 🆕
Storage Compatibility (LVM/file-based)
OpenAPI Integration (port 8811)
Open WebUI Integration
Error Handling & Validation
Complete Documentation & Testing
Production Ready!
ProxmoxMCP Plus is now fully ready for production use!
When users say "Can you create a VM with 1 cpu core and 2 GB ram with 10GB of storage disk", the AI assistant can:
📞 Call the
create_vm
API🔧 Automatically select appropriate storage and format
🎯 Create VMs that match requirements
📊 Return detailed configuration information
💡 Provide next-step recommendations
Development
After activating your virtual environment:
Run tests:
pytest
Format code:
black .
Type checking:
mypy .
Lint:
ruff .
License
MIT License
Special Thanks
Thanks to @canvrno for the excellent foundational project ProxmoxMCP
Thanks to the Proxmox community for providing the powerful virtualization platform
Thanks to all contributors and users for their support
Ready to Deploy! 🎉 Your enhanced Proxmox MCP service with OpenAPI integration is ready for production use.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
An enhanced Python-based MCP server that enables complete VM lifecycle management and monitoring of Proxmox virtualization platforms through natural language, with 11 REST API endpoints for seamless integration.
Related MCP Servers
- -securityAlicense-qualityA Python-based server enabling interaction with Proxmox hypervisors. It supports secure authentication and provides tools for managing nodes, VMs, clusters, and storage.Last updated -155MIT License
- -securityFlicense-qualityThis is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.Last updated -
- -securityAlicense-qualityA VMware ESXi/vCenter management server based on MCP (Machine Control Protocol), providing simple REST API interfaces for virtual machine management.Last updated -38MIT License
- -securityAlicense-qualityA Python-based Model Context Protocol server that enables managing Proxmox virtualization platform through Cursor IDE, supporting complete VM lifecycle management including creation, power control, and deletion.Last updated -9MIT License