š Proxmox Manager - Proxmox MCP Server
A Python-based Model Context Protocol (MCP) server for interacting with Proxmox hypervisors, providing a clean interface for managing nodes, VMs, and containers.
šļø Built With
- Cline - Autonomous coding agent - Go faster with Cline.
- Proxmoxer - Python wrapper for Proxmox API
- MCP SDK - Model Context Protocol SDK
- Pydantic - Data validation using Python type annotations
āØ Features
- š¤ Full integration with Cline
- š ļø Built with the official MCP SDK
- š Secure token-based authentication with Proxmox
- š„ļø Tools for managing nodes and VMs
- š» VM console command execution
- š Configurable logging system
- ā
Type-safe implementation with Pydantic
- šØ Rich output formatting with customizable themes
https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b
š¦ Installation
Prerequisites
- UV package manager (recommended)
- Python 3.10 or higher
- Git
- Access to a Proxmox server with API token credentials
Before starting, ensure you have:
Option 1: Quick Install (Recommended)
-
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
}
}
Verifying Installation
-
Check Python environment:
python -c "import proxmox_mcp; print('Installation OK')"
-
Run the tests:
-
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:
- A successful connection to your Proxmox server
- Or a connection error (if Proxmox details are incorrect)
āļø Configuration
Proxmox API Token Setup
- Log into your Proxmox web interface
- Navigate to Datacenter -> Permissions -> API Tokens
- 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
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": {
"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:
- All paths must be absolute
- The Python interpreter must be from your virtual environment
- The PYTHONPATH must point to the src directory
- Restart VSCode after updating MCP settings
š§ Available Tools
The server provides the following MCP tools for interacting with Proxmox:
get_nodes
Lists all nodes in the Proxmox cluster.
get_node_status
Get detailed status of a specific node.
get_vms
List all VMs across the cluster.
get_storage
List available storage.
get_cluster_status
Get overall cluster status.
execute_vm_command
Execute a command in a VM's console using QEMU Guest Agent.
šØāš» Development
After activating your virtual environment:
- Run tests:
pytest
- Format code:
black .
- Type checking:
mypy .
- Lint:
ruff .
š Project Structure
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
š License
MIT License
