Skip to main content
Glama

Proxmox MCP Server

by canvrno

🚀 Proxmox Manager - Proxmox MCP Server

ProxmoxMCP

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

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

  • 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

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

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Python-based server enabling interaction with Proxmox hypervisors. It supports secure authentication and provides tools for managing nodes, VMs, clusters, and storage.

  1. 🏗️ Built With
    1. ✨ Features
      1. 📦 Installation
        1. Prerequisites
        2. Option 1: Quick Install (Recommended)
        3. Verifying Installation
      2. ⚙️ Configuration
        1. Proxmox API Token Setup
      3. 🚀 Running the Server
        1. Development Mode
        2. Cline Desktop Integration
      4. 🔧 Available Tools
        1. get_nodes
        2. get_node_status
        3. get_vms
        4. get_storage
        5. get_cluster_status
        6. execute_vm_command
        7. 👨‍💻 Development
        8. 📁 Project Structure
        9. 📄 License

      Related MCP Servers

      • -
        security
        F
        license
        -
        quality
        This is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.
        Last updated -
        Python
      • -
        security
        F
        license
        -
        quality
        A server that securely manages Ethereum private keys locally and enables Claude for Desktop to interact with EVM-compatible blockchains through Infura.
        Last updated -
        TypeScript
      • -
        security
        A
        license
        -
        quality
        A Python server implementation that enables integration with the PeakMojo API, providing access to various resources like users, personas, scenarios, and tools for managing PeakMojo functionality.
        Last updated -
        Python
        MIT License
        • Linux
      • A
        security
        A
        license
        A
        quality
        A server that provides a persistent Python REPL environment through the MCP protocol, allowing execution of Python code, variable management, and package installation.
        Last updated -
        3
        3
        Python
        MIT License

      View all related MCP servers

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/canvrno/ProxmoxMCP'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server