adrianlizman/proxmox-mcp-server
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.
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
- Clone the repository:
git clone https://github.com/adrianlizman/proxmox-mcp-server.git
cd proxmox-mcp-server
- Configure environment:
cp config/.env.example config/.env
# Edit config/.env with your Proxmox credentials and settings
- 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
- Start the stack:
docker-compose up -d
- Initialize Ollama models:
docker exec ollama ollama pull llama2
docker exec ollama ollama pull codellama
- Import n8n workflows:
# Workflows are automatically mounted from ./workflows/
# Access n8n at http://localhost:5678 to activate them
Access Points
- MCP Server: http://localhost:8080
- n8n Workflows: http://localhost:5678
- Grafana Dashboard: http://localhost:3000
- Prometheus: http://localhost:9091
๐ API Documentation
MCP Tools
Tool | Description | Parameters |
---|---|---|
list_vms | List virtual machines | node? , status? |
get_vm_details | Get VM details | node , vmid |
create_vm | Create new VM | node , vmid , config |
start_vm | Start VM | node , vmid |
stop_vm | Stop VM | node , vmid , force? |
delete_vm | Delete VM | node , vmid , purge? |
clone_vm | Clone VM | node , vmid , newid , config? |
migrate_vm | Migrate VM | node , vmid , target_node , config? |
list_containers | List LXC containers | node? , status? |
create_container | Create container | node , vmid , config |
get_cluster_status | Get cluster status | - |
get_cluster_resources | Get cluster resources | type? |
list_storages | List storage configs | node? |
get_storage_status | Get storage status | node , storage |
create_backup | Create backup | node , vmid , config |
list_backups | List backups | node? , 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
-
VM Lifecycle Automation
- Automatic notifications for VM state changes
- Post-creation configuration and monitoring setup
- Failure detection and alerting
-
Backup Automation
- Scheduled daily backups
- Intelligent backup retention
- Failure notifications and retry logic
-
Performance Monitoring
- Real-time resource monitoring
- Threshold-based alerting
- AI-powered recommendations
-
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
Variable | Description | Default |
---|---|---|
PROXMOX_HOST | Proxmox VE hostname | Required |
PROXMOX_USERNAME | Username for Proxmox | Required |
PROXMOX_PASSWORD | Password for Proxmox | Required |
SECRET_KEY | JWT secret key | Required |
OLLAMA_MODEL | AI model to use | llama2 |
ENABLE_AI_FEATURES | Enable AI integration | true |
ENABLE_N8N_INTEGRATION | Enable n8n workflows | true |
LOG_LEVEL | Logging level | INFO |
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
-
Hardware Requirements:
- CPU: 4+ cores
- RAM: 8GB+ (16GB recommended with AI)
- Storage: 100GB+ SSD
- Network: 1Gbps+
-
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
- 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
๐ License
This project is licensed under the MIT License - see the file for details.
๐ Support
- Documentation:
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: support@yourdomain.com
๐ 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