Proxmox

Proxmox mcp server

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "teomarcdhio-proxmox-mcp": {
      "command": "uv",
      "args": [
        "run",
        "proxmox-mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "PROXMOX_HOST": "YOUR_PROXMOX_HOST",
        "PROXMOX_PORT": "8006",
        "PROXMOX_VERIFY_SSL": "false",
        "PROXMOX_API_TOKEN_ID": "user@pve!tokenid",
        "PROXMOX_API_TOKEN_SECRET": "s3cr3t"
      }
    }
  }
}

You deploy a read-only MCP server that lets LLM agents query and monitor your Proxmox homelab VMs without risking changes. It offers a safe, unified way to list VMs, view detailed configurations, monitor runtime metrics, and inspect snapshots across your Proxmox cluster.

How to use

You connect your MCP client to the Proxmox MCP Server to perform read-only actions. Use the server to list all VMs and containers, fetch detailed VM information, monitor current status with real-time metrics, retrieve historical performance data, list VM snapshots, and inspect cluster health. All operations are read-only, so your virtual machines remain safe from unintended changes.

How to install

Prerequisites: you need a runtime environment to launch the MCP server. The following options show how to start the server using two common runtimes.

curl -LsSf https://astral.sh/uv/install.sh | sh

pip install -e .
proxmox-mcp --transport sse

cd proxmox-mcp

# SSE mode (recommended for remote access)
uv run proxmox-mcp --transport sse

# Or stdio mode (for local VS Code/CLI usage)
uv run proxmox-mcp --transport stdio

Alternative: install globally with pip

pip install -e .
proxmox-mcp --transport sse

Configuration and usage notes

Configure connectivity and access using environment variables or a .env file. The key settings include your Proxmox host, API token, and the MCP server bind settings. The following configuration options are commonly used to enable secure, reliable operation.

PROXMOX_HOST=your-proxmox-host
PROXMOX_PORT=8006
PROXMOX_VERIFY_SSL=false
PROXMOX_API_TOKEN_ID=your-token-id
PROXMOX_API_TOKEN_SECRET=your-token-secret
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8080

Security reminders

Use API tokens instead of usernames and passwords. Favor a dedicated auditor user with read-only permissions. Run behind a reverse proxy with HTTPS for production use, and firewall the MCP port to trusted networks only.

Available tools

list_vms

List all VMs and containers with basic information across the Proxmox cluster.

get_vm_info

Retrieve detailed configuration and hardware information for a single VM.

get_vm_status

Get current runtime status and real-time metrics for a VM.

get_vm_metrics

Fetch historical performance data for one or more VMs.

get_vm_filesystem_info

Obtain disk space information from inside a VM (requires guest agent).

list_nodes

List all Proxmox nodes in the cluster.

list_vm_snapshots

List available snapshots for a VM.

get_cluster_status

Provide cluster health, totals, and overall status.