Python-based Model Context Protocol server enabling secure, type-safe management of Proxmox hypervisors with API token authentication, VM and node control, console command execution, and customizable logging.
Unlock the full potential of Proxmox MCP Server through LangDB's AI Gateway. Get enterprise-grade security, analytics, and seamless integration with zero configuration.
Free tier available • No credit card required
A Python-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers.
https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b
Before starting, ensure you have:
pip install uv
)Clone and set up environment:
# Clone repository cd ~/Documents/Cline/MCP # For Cline users # OR cd your/preferred/directory # For manual installation git clone https://github.com/canvrno/ProxmoxMCP.git cd ProxmoxMCP # Create and activate virtual environment uv venv source .venv/bin/activate # Linux/macOS # OR .\.venv\Scripts\Activate.ps1 # Windows
Install dependencies:
# Install with development dependencies uv pip install -e ".[dev]"
Create configuration:
# Create config directory and copy template mkdir -p proxmox-config cp config/config.example.json proxmox-config/config.json
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 } }
Check Python environment:
python -c "import proxmox_mcp; print('Installation OK')"
Run the tests:
pytest
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
You should see either:
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
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": { "github.com/canvrno/ProxmoxMCP": { "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python", "args": ["-m", "proxmox_mcp.server"], "cwd": "/absolute/path/to/ProxmoxMCP", "env": { "PYTHONPATH": "/absolute/path/to/ProxmoxMCP/src", "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/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": [] } } }
To help generate the correct paths, you can use this command:
# This will print the MCP settings with your absolute paths filled in python -c "import os; print(f'''{{ "mcpServers": {{ "github.com/canvrno/ProxmoxMCP": {{ "command": "{os.path.abspath('.venv/bin/python')}", "args": ["-m", "proxmox_mcp.server"], "cwd": "{os.getcwd()}", "env": {{ "PYTHONPATH": "{os.path.abspath('src')}", "PROXMOX_MCP_CONFIG": "{os.path.abspath('proxmox-config/config.json')}", ... }} }} }} }}''')"
Important:
The server provides the following MCP tools for interacting with Proxmox:
Lists all nodes in the Proxmox cluster.
🖥️ Proxmox Nodes
🖥️ pve-compute-01
• Status: ONLINE
• Uptime: ⏳ 156d 12h
• CPU Cores: 64
• Memory: 186.5 GB / 512.0 GB (36.4%)
🖥️ pve-compute-02
• Status: ONLINE
• Uptime: ⏳ 156d 11h
• CPU Cores: 64
• Memory: 201.3 GB / 512.0 GB (39.3%)
Get detailed status of a specific node.
node
(string, required): Name of the node🖥️ Node: pve-compute-01
• Status: ONLINE
• Uptime: ⏳ 156d 12h
• CPU Usage: 42.3%
• CPU Cores: 64 (AMD EPYC 7763)
• Memory: 186.5 GB / 512.0 GB (36.4%)
• Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s
• Temperature: 38°C
List all VMs across the cluster.
🗃️ Virtual Machines
🗃️ prod-db-master (ID: 100)
• Status: RUNNING
• Node: pve-compute-01
• CPU Cores: 16
• Memory: 92.3 GB / 128.0 GB (72.1%)
🗃️ prod-web-01 (ID: 102)
• Status: RUNNING
• Node: pve-compute-01
• CPU Cores: 8
• Memory: 12.8 GB / 32.0 GB (40.0%)
List available storage.
💾 Storage Pools
💾 ceph-prod
• Status: ONLINE
• Type: rbd
• Usage: 12.8 TB / 20.0 TB (64.0%)
• IOPS: ⬆️ 15.2k ⬇️ 12.8k
💾 local-zfs
• Status: ONLINE
• Type: zfspool
• Usage: 3.2 TB / 8.0 TB (40.0%)
• IOPS: ⬆️ 42.8k ⬇️ 35.6k
Get overall cluster status.
⚙️ Proxmox Cluster
• Name: enterprise-cloud
• Status: HEALTHY
• Quorum: OK
• Nodes: 4 ONLINE
• Version: 8.1.3
• HA Status: ACTIVE
• Resources:
- Total CPU Cores: 192
- Total Memory: 1536 GB
- Total Storage: 70 TB
• Workload:
- Running VMs: 7
- Total VMs: 8
- Average CPU Usage: 38.6%
- Average Memory Usage: 42.8%
Execute a command in a VM's console using QEMU Guest Agent.
node
(string, required): Name of the node where VM is runningvmid
(string, required): ID of the VMcommand
(string, required): Command to execute🔧 Console Command Result
• Status: SUCCESS
• Command: systemctl status nginx
• Node: pve-compute-01
• VM: prod-web-01 (ID: 102)
Output:
● nginx.service - A high performance web server and a reverse proxy server
Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago
After activating your virtual environment:
pytest
black .
mypy .
ruff .
proxmox-mcp/
├── src/
│ └── proxmox_mcp/
│ ├── server.py # Main MCP server implementation
│ ├── config/ # Configuration handling
│ ├── core/ # Core functionality
│ ├── formatting/ # Output formatting and themes
│ ├── tools/ # Tool implementations
│ │ └── console/ # VM console operations
│ └── utils/ # Utilities (auth, logging)
├── tests/ # Test suite
├── proxmox-config/
│ └── config.example.json # Configuration template
├── pyproject.toml # Project metadata and dependencies
└── LICENSE # MIT License
MIT License
Discover shared experiences
Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!