proxmox-mcp-server

adrianlizman/proxmox-mcp-server

3.2

If you are the rightful owner of proxmox-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Proxmox MCP Server is a comprehensive solution for managing Proxmox VE environments, integrating AI insights and workflow automation.

Tools
5
Resources
0
Prompts
0

Proxmox MCP Server

A comprehensive Model Context Protocol (MCP) server for Proxmox VE management with production-ready features, AI-powered insights via Ollama, and workflow automation through n8n integration.

๐Ÿš€ Features

Core Proxmox Operations

  • VM Management: Create, delete, start, stop, clone, migrate, and template VMs
  • Container Management: Full LXC container lifecycle management
  • Cluster Operations: Monitor cluster health, manage HA resources, and resource pools
  • Storage Management: Configure storage backends, monitor usage, and manage volumes
  • Network Management: Create bridges, VLANs, bonds, and SDN configurations
  • Node Management: Monitor nodes, manage services, and perform maintenance
  • Backup Operations: Automated backup creation, restoration, and cleanup

Production Features

  • Security: JWT authentication, RBAC integration, SSL/TLS support
  • Logging: Comprehensive audit trails and structured logging
  • Error Handling: Robust exception management with retry logic
  • Configuration: Environment-based settings with validation
  • Health Monitoring: Service health checks and diagnostics
  • Metrics: Prometheus integration for monitoring and alerting

AI Integration (Ollama)

  • Performance Analysis: AI-powered VM and container performance insights
  • Resource Optimization: Intelligent resource sizing recommendations
  • Troubleshooting: Automated issue diagnosis and resolution suggestions
  • Capacity Planning: Predictive analysis for infrastructure scaling
  • Best Practices: Context-aware operational recommendations

Workflow Automation (n8n)

  • Lifecycle Management: Automated VM/container provisioning workflows
  • Performance Monitoring: Real-time alerting and auto-remediation
  • Backup Automation: Scheduled backups with intelligent cleanup
  • Maintenance Workflows: Automated maintenance scheduling and execution
  • Custom Integrations: Webhook-driven custom workflow triggers

๐Ÿ—๏ธ Architecture

graph TB
    subgraph "Client Layer"
        MCP[MCP Client]
        API[REST API]
        WEB[Web Interface]
    end
    
    subgraph "Proxmox MCP Server"
        AUTH[Authentication]
        RBAC[Authorization]
        CORE[Core Services]
        AI[AI Advisor]
        N8N[n8n Integration]
    end
    
    subgraph "External Services"
        PVE[Proxmox VE]
        OLLAMA[Ollama LLM]
        N8N_SVC[n8n Workflows]
        PROM[Prometheus]
    end
    
    MCP --> AUTH
    API --> AUTH
    WEB --> AUTH
    
    AUTH --> RBAC
    RBAC --> CORE
    CORE --> AI
    CORE --> N8N
    
    CORE --> PVE
    AI --> OLLAMA
    N8N --> N8N_SVC
    CORE --> PROM

๐Ÿš€ Quick Start

Prerequisites

  • Docker and Docker Compose
  • Proxmox VE cluster (6.0+)
  • 4GB+ RAM for full stack
  • Optional: NVIDIA GPU for AI features

Installation

  1. Clone the repository:
git clone https://github.com/adrianlizman/proxmox-mcp-server.git
cd proxmox-mcp-server
  1. Configure environment:
cp config/.env.example config/.env
# Edit config/.env with your Proxmox credentials and settings
  1. Generate SSL certificates (optional):
mkdir -p config/nginx/ssl
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout config/nginx/ssl/proxmox-mcp.key \
    -out config/nginx/ssl/proxmox-mcp.crt
  1. Start the stack:
docker-compose up -d
  1. Initialize Ollama models:
docker exec ollama ollama pull llama2
docker exec ollama ollama pull codellama
  1. Import n8n workflows:
# Workflows are automatically mounted from ./workflows/
# Access n8n at http://localhost:5678 to activate them

Access Points

๐Ÿ“– API Documentation

MCP Tools

ToolDescriptionParameters
list_vmsList virtual machinesnode?, status?
get_vm_detailsGet VM detailsnode, vmid
create_vmCreate new VMnode, vmid, config
start_vmStart VMnode, vmid
stop_vmStop VMnode, vmid, force?
delete_vmDelete VMnode, vmid, purge?
clone_vmClone VMnode, vmid, newid, config?
migrate_vmMigrate VMnode, vmid, target_node, config?
list_containersList LXC containersnode?, status?
create_containerCreate containernode, vmid, config
get_cluster_statusGet cluster status-
get_cluster_resourcesGet cluster resourcestype?
list_storagesList storage configsnode?
get_storage_statusGet storage statusnode, storage
create_backupCreate backupnode, vmid, config
list_backupsList backupsnode?, storage?

REST API Endpoints

# Authentication
POST /api/v1/auth/login
POST /api/v1/auth/refresh

# VMs
GET    /api/v1/vms
POST   /api/v1/vms
GET    /api/v1/vms/{vmid}
PUT    /api/v1/vms/{vmid}
DELETE /api/v1/vms/{vmid}
POST   /api/v1/vms/{vmid}/start
POST   /api/v1/vms/{vmid}/stop
POST   /api/v1/vms/{vmid}/clone
POST   /api/v1/vms/{vmid}/migrate

# Containers
GET    /api/v1/containers
POST   /api/v1/containers
GET    /api/v1/containers/{vmid}
DELETE /api/v1/containers/{vmid}

# Cluster
GET    /api/v1/cluster/status
GET    /api/v1/cluster/resources
GET    /api/v1/cluster/nodes

# AI Integration
POST   /api/v1/ai/analyze-vm
POST   /api/v1/ai/analyze-container
POST   /api/v1/ai/analyze-cluster
POST   /api/v1/ai/suggest-sizing
POST   /api/v1/ai/troubleshoot

# Workflows
POST   /api/v1/workflows/trigger
GET    /api/v1/workflows/status

๐Ÿค– AI Features

Performance Analysis

# Analyze VM performance
result = await ai_advisor.analyze_vm_performance({
    'vmid': 100,
    'node': 'pve1',
    'cpu': 0.8,
    'maxcpu': 4,
    'mem': 2147483648,
    'maxmem': 4294967296
})

print(result['ai_recommendations'])
print(result['automated_suggestions'])

Resource Sizing

# Get sizing recommendations
sizing = await ai_advisor.suggest_resource_sizing(
    workload_type='web_server',
    requirements={
        'expected_users': 1000,
        'peak_traffic': '10k requests/hour',
        'database': 'mysql',
        'framework': 'django'
    }
)

Troubleshooting

# Get troubleshooting help
help_result = await ai_advisor.troubleshoot_issue(
    issue_description='VM is running slowly',
    system_data={
        'vm_id': 100,
        'symptoms': ['high CPU usage', 'slow response'],
        'recent_changes': ['memory upgrade']
    }
)

๐Ÿ”„ Workflow Automation

Available Workflows

  1. VM Lifecycle Automation

    • Automatic notifications for VM state changes
    • Post-creation configuration and monitoring setup
    • Failure detection and alerting
  2. Backup Automation

    • Scheduled daily backups
    • Intelligent backup retention
    • Failure notifications and retry logic
  3. Performance Monitoring

    • Real-time resource monitoring
    • Threshold-based alerting
    • AI-powered recommendations
  4. Maintenance Automation

    • Scheduled maintenance windows
    • Automatic VM migration for node updates
    • Post-maintenance verification

Custom Workflow Integration

// n8n webhook example
{
  "event_type": "vm_created",
  "vm": {
    "vmid": 100,
    "name": "web-server-01",
    "node": "pve1",
    "status": "running"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

๐Ÿ”ง Configuration

Environment Variables

VariableDescriptionDefault
PROXMOX_HOSTProxmox VE hostnameRequired
PROXMOX_USERNAMEUsername for ProxmoxRequired
PROXMOX_PASSWORDPassword for ProxmoxRequired
SECRET_KEYJWT secret keyRequired
OLLAMA_MODELAI model to usellama2
ENABLE_AI_FEATURESEnable AI integrationtrue
ENABLE_N8N_INTEGRATIONEnable n8n workflowstrue
LOG_LEVELLogging levelINFO

Security Configuration

# RBAC Roles
admin:
  - vm:*, lxc:*, cluster:*, storage:*, network:*, backup:*
  
operator:
  - vm:start, vm:stop, vm:clone, vm:monitor
  - lxc:start, lxc:stop, lxc:monitor
  - backup:create, backup:monitor
  
viewer:
  - vm:monitor, lxc:monitor, cluster:monitor
  - storage:monitor, network:monitor

๐Ÿ“Š Monitoring

Metrics

  • VM/Container resource utilization
  • API request rates and latencies
  • Backup success/failure rates
  • Cluster health indicators
  • AI analysis response times

Dashboards

  • Proxmox Cluster Overview
  • VM/Container Performance
  • Storage Utilization
  • Backup Status
  • API Performance

Alerting Rules

groups:
  - name: proxmox.rules
    rules:
      - alert: HighCPUUsage
        expr: vm_cpu_usage > 90
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High CPU usage on VM {{ $labels.vmid }}"

๐Ÿ”’ Security

Authentication

  • JWT-based API authentication
  • Proxmox VE credential validation
  • Session management and refresh tokens

Authorization

  • Role-based access control (RBAC)
  • Fine-grained permission system
  • Resource-level access controls

Network Security

  • TLS/SSL encryption
  • Rate limiting and DDoS protection
  • Network segmentation support

Audit Logging

  • Comprehensive operation logging
  • Security event tracking
  • Compliance reporting

๐Ÿš€ Deployment

Production Deployment

  1. Hardware Requirements:

    • CPU: 4+ cores
    • RAM: 8GB+ (16GB recommended with AI)
    • Storage: 100GB+ SSD
    • Network: 1Gbps+
  2. Security Hardening:

# Generate strong secrets
openssl rand -hex 32 > .secret_key

# Configure SSL certificates
certbot certonly --standalone -d proxmox-mcp.yourdomain.com

# Set up firewall rules
ufw allow 443/tcp
ufw allow 80/tcp
ufw deny 8080/tcp  # Block direct access
  1. High Availability:
# docker-compose.prod.yml
services:
  proxmox-mcp-server:
    deploy:
      replicas: 3
      restart_policy:
        condition: on-failure
        max_attempts: 3

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: proxmox-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: proxmox-mcp-server
  template:
    metadata:
      labels:
        app: proxmox-mcp-server
    spec:
      containers:
      - name: proxmox-mcp-server
        image: proxmox-mcp-server:latest
        ports:
        - containerPort: 8080
        env:
        - name: PROXMOX_HOST
          valueFrom:
            secretKeyRef:
              name: proxmox-credentials
              key: host

๐Ÿงช Development

Setup Development Environment

# Clone repository
git clone https://github.com/your-org/proxmox-mcp-server.git
cd proxmox-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Start development server
python -m src.main

Code Quality

# Format code
black src/
isort src/

# Lint code
flake8 src/
mypy src/

# Run security checks
bandit -r src/

Testing

# Unit tests
pytest tests/unit/

# Integration tests
pytest tests/integration/

# Load tests
pytest tests/load/

# Coverage report
pytest --cov=src tests/

๐Ÿ“š Documentation

๐Ÿค Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“„ License

This project is licensed under the MIT License - see the file for details.

๐Ÿ†˜ Support

๐Ÿ™ Acknowledgments

  • Proxmox VE for the excellent virtualization platform
  • MCP Protocol for the standardized AI integration
  • Ollama for local LLM capabilities
  • n8n for workflow automation
  • The open-source community for continuous inspiration

Made with โค๏ธ for the Proxmox community