Skip to Content
MCP ServersCommunityπŸš€ Proxmox Manager - Proxmox MCP Server

πŸš€ Proxmox Manager - Proxmox MCP Server

View original on GitHub 

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

✨ 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

Last updated on
ProtoLinkAI πŸš€PulseMCP Server