Proxmoxmcp Plus

🚀 ProxmoxMCP-Plus - Enhanced Proxmox MCP Server

ProxmoxMCP-Plus is an enhanced Python-based Model Context Protocol (MCP) server designed for seamless interaction with Proxmox virtualization platforms. Built upon the foundation of canvrno/ProxmoxMCP, it comes with numerous new features and improvements. It offers complete OpenAPI integration and more powerful virtualization management capabilities, enabling users to manage Proxmox environments more efficiently.

🚀 Quick Start

Before you begin, ensure you have the necessary prerequisites installed and configured. Then, you can follow the installation steps to set up ProxmoxMCP-Plus on your system. After installation, you can start the server and begin using its features.

✨ Features

• 🤖 Full integration with Cline and Open WebUI, providing a seamless user experience.
• 🛠️ Built with the official MCP SDK, ensuring compatibility and reliability.
• 🔒 Secure token-based authentication with Proxmox, protecting your data and resources.
• 🖥️ Complete VM lifecycle management (create, start, stop, reset, shutdown, delete), giving you full control over your virtual machines.
• 💻 VM console command execution, allowing you to interact with VMs directly.
• 🐳 LXC container management support, enabling you to manage containers efficiently.
• 🗃️ Intelligent storage type detection (LVM/file-based), automatically selecting the appropriate storage format.
• 📝 Configurable logging system, helping you track and troubleshoot issues.
• ✅ Type-safe implementation with Pydantic, ensuring code quality and reliability.
• 🎨 Rich output formatting with customizable themes, enhancing the visual appeal of the output.
• 🌐 OpenAPI REST endpoints for integration, making it easy to integrate with other applications.
• 📡 11 fully functional API endpoints, providing comprehensive functionality.

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

1. 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  # Windows
   

2. Install dependencies:

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

3. Create configuration:

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

4. Edit 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

1. Check Python environment:

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

2. Run the tests:

   pytest
   

3. Verify 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
   

📚 Documentation

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

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

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

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

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

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 (create/power) 🆕
│       │   ├── 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;
    }
}

Troubleshooting

Common Issues

1. Port already in use

   netstat -tlnp | grep 8811
   # Change port if needed
   mcpo --port 8812 -- ./start_server.sh
   

2. Configuration errors

   # Verify config file
   cat proxmox-config/config.json
   

3. Connection issues

   # Test Proxmox connectivity
   curl -k https://your-proxmox:8006/api2/json/version
   

View Logs

# View service logs
tail -f proxmox_mcp.log

# Docker logs
docker logs proxmox-mcp-api -f

Deployment Status

✅ Feature Completion: 100%

• [x] VM Creation (user requirement: 1 CPU + 2GB RAM + 10GB storage) 🆕
• [x] VM Power Management (start VPN-Server ID:101) 🆕
• [x] VM Deletion Feature 🆕
• [x] Container Management (LXC) 🆕
• [x] Storage Compatibility (LVM/file-based)
• [x] OpenAPI Integration (port 8811)
• [x] Open WebUI Integration
• [x] Error Handling & Validation
• [x] 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:

1. 📞 Call the create_vm API
2. 🔧 Automatically select appropriate storage and format
3. 🎯 Create VMs that match requirements
4. 📊 Return detailed configuration information
5. 💡 Provide next-step recommendations

Development

After activating your virtual environment:

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

📄 License

This project is licensed under the MIT License.

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! Also, thanks to the Proxmox community for providing the powerful virtualization platform and all contributors and users for their support.

Ready to Deploy! 🎉 Your enhanced Proxmox MCP service with OpenAPI integration is ready for production use.