Proxmox

You run a Python-based MCP server that provides a clean interface to manage Proxmox nodes, virtual machines, and storage. It lets you query cluster status, fetch node and VM details, and execute commands inside VM consoles through a simple, programmable API.

How to use

You interact with this MCP server by starting it in your environment and connecting a client that speaks the MCP protocol. The server exposes a set of tools to retrieve status, list resources, and perform actions such as running commands inside VM consoles. Use a client to send requests for nodes, VMs, storage, and cluster information, then display or act on the responses in your workflow or editor integrations.

How to install

Prerequisites provide the foundation to run the MCP server and connect to Proxmox.

• Python 3.10 or higher
• Git
• A Proxmox server with API token credentials
• UV package manager (recommended)

Follow these concrete steps to install and run the MCP server.

# 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
uv pip install -e ".[dev]"

# Create configuration
mkdir -p proxmox-config
cp config/config.example.json proxmox-config/config.json

# Edit proxmox-config/config.json with your Proxmox and token details
{
  "proxmox": {
    "host": "PROXMOX_HOST",
    "port": 8006,
    "verify_ssl": false,
    "service": "PVE"
  },
  "auth": {
    "user": "USER@pve",
    "token_name": "TOKEN_NAME",
    "token_value": "TOKEN_VALUE"
  },
  "logging": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "file": "proxmox_mcp.log"
  }
}
"]}]},{

Configuration and security

Configure authentication against Proxmox using an API token and adjust the server’s logging level to suit your environment. For security, keep tokens secret and restrict privileges as needed.

# Example of starting the development server

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\\.venv\\Scripts\\Activate.ps1  # Windows

# Run the server
python -m proxmox_mcp.server

# When running from external tooling, you may pass a config path
# PROXMOX_MCP_CONFIG=proxmox-config/config.json python -m proxmox_mcp.server

"}]} ,{

Notes and troubleshooting

If you encounter connection issues, verify your Proxmox host, port, and API token values. Ensure the token has sufficient permissions for the actions you intend to perform. Check the generated log file for details and enable DEBUG logging to troubleshoot more deeply.

# Enable debug logging by setting the environment variable or config value
LOG_LEVEL: DEBUG
# Restart the server after changes
"}]}]},

Tools and endpoints

The MCP server exposes a set of tools to query and manage the Proxmox cluster. Use a client to invoke these tools and present the results in your workflow.

Available tools

get_nodes

Lists all nodes in the Proxmox cluster.

get_node_status

Gets detailed status for a specific node.

get_vms

Lists all virtual machines across the cluster.

get_storage

Lists available storage pools.

get_cluster_status

Provides an overview of the entire Proxmox cluster status.

execute_vm_command

Executes a command inside a VM's console via the QEMU Guest Agent.