🚀 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:

• Proxmox server hostname or IP

• Proxmox API token (see API Token Setup)

• UV installed (pip install uv)

Option 1: Quick Install (Recommended)

1. 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

2. Install dependencies:

   # Install with development dependencies uv pip install -e ".[dev]"

3. Create configuration:

   # Create config directory and copy template mkdir -p proxmox-config cp config/config.example.json proxmox-config/config.json

4. 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

1. Check Python environment:

   python -c "import proxmox_mcp; print('Installation OK')"

2. Run the tests:

   pytest

3. 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

1. Log into your Proxmox web interface

2. Navigate to Datacenter -> Permissions -> API Tokens

3. 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:

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):

To help generate the correct paths, you can use this command:

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.

• Parameters: None

• Example Response:

  🖥️ 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_node_status

Get detailed status of a specific node.

• Parameters:

  • node (string, required): Name of the node

• Example Response:

  🖥️ 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

get_vms

List all VMs across the cluster.

• Parameters: None

• Example Response:

  🗃️ 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%)

get_storage

List available storage.

• Parameters: None

• Example Response:

  💾 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_cluster_status

Get overall cluster status.

• Parameters: None

• Example Response:

  ⚙️ 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_vm_command

Execute a command in a VM's console using QEMU Guest Agent.

• Parameters:

  • node (string, required): Name of the node where VM is running

  • vmid (string, required): ID of the VM

  • command (string, required): Command to execute

• Example Response:

  🔧 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

• Requirements:

  • VM must be running

  • QEMU Guest Agent must be installed and running in the VM

  • Command execution permissions must be enabled in the Guest Agent

• Error Handling:

  • Returns error if VM is not running

  • Returns error if VM is not found

  • Returns error if command execution fails

  • Includes command output even if command returns non-zero exit code

👨‍💻 Development

After activating your virtual environment:

• Run tests: pytest

• Format code: black .

• Type checking: mypy .

• Lint: ruff .

📁 Project Structure

📄 License

MIT License