mcp-proxmox/ClineInstall.md

Cline Installation Guide

This guide provides specific instructions for Cline to install and configure the Proxmox MCP server.

Prerequisites

• UV package manager
• Python 3.9 or higher
• Access to a Proxmox server with API token credentials

Installation Steps

1. Environment Setup

# Clone repository into Cline MCP directory
cd ~/Documents/Cline/MCP
git clone https://github.com/canvrno/ProxmoxMCP.git
cd ProxmoxMCP

# Create and activate virtual environment using UV
uv venv
source .venv/bin/activate

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

2. Configuration Setup

Create the config directory and config.json file:

mkdir -p proxmox-config

Create proxmox-config/config.json with the following structure:

{
    "proxmox": {
        "host": "your-proxmox-host",  # Hostname or IP of Proxmox server
        "port": 8006,                 # Default Proxmox API port
        "verify_ssl": true,           # Set to false if using self-signed certs
        "service": "PVE"              # Default Proxmox service
    },
    "auth": {
        "user": "username@pve",       # Proxmox username with @pve suffix
        "token_name": "token-name",   # API token name
        "token_value": "token-value"  # API token value
    },
    "logging": {
        "level": "INFO",              # DEBUG for more verbose logging
        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        "file": "proxmox_mcp.log"     # Log file name
    }
}

3. MCP Server Configuration

Add the following configuration to the Cline 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": []
        }
    }
}

Critical Requirements

1. Virtual Environment:

   • The virtual environment MUST be used for both installation and running the server
   • All Python commands should be run within the activated venv

2. File Paths:

   • ALL paths in the MCP settings must be absolute paths
   • The PYTHONPATH must point to the src directory
   • The PROXMOX_MCP_CONFIG environment variable must point to your config.json file

3. Environment Variables:

   • PROXMOX_MCP_CONFIG is required for the server to locate your configuration
   • All Proxmox-related environment variables can override config.json settings

4. VSCode Integration:

   • Restart VSCode after updating MCP settings
   • The server will be available through the MCP tools interface

Troubleshooting

1. Import Errors:

   • Ensure PYTHONPATH is set correctly
   • Verify the package is installed in development mode
   • Make sure you're using the Python interpreter from the virtual environment

2. Configuration Errors:

   • Check that PROXMOX_MCP_CONFIG points to a valid config.json file
   • Verify all required fields are present in config.json
   • Ensure Proxmox credentials are correct

3. Connection Issues:

   • Verify Proxmox host is reachable
   • Check if SSL verification is appropriate for your setup
   • Confirm API token has necessary permissions

Available Tools

Once installed, the following tools will be available:

1. get_nodes: List all nodes in the cluster
2. get_node_status: Get detailed status of a specific node
3. get_vms: List all VMs across the cluster
4. get_storage: List available storage
5. get_cluster_status: Get cluster status
6. execute_vm_command: Run commands in VM consoles

Example usage:

# Get cluster status
use_mcp_tool(
    server_name="github.com/canvrno/ProxmoxMCP",
    tool_name="get_cluster_status",
    arguments={}
)

# Get status of specific node
use_mcp_tool(
    server_name="github.com/canvrno/ProxmoxMCP",
    tool_name="get_node_status",
    arguments={"node": "pve1"}
)