MCP for Proxmox integration in Cline
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
{ "mcpServers": { "proxmoxmcp": { "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python", "args": [ "-m", "proxmox_mcp.server" ] } } }
Related projects feature coming soon
Will recommend related projects based on sub-categories