MCP Proxmox Server

You set up and run an MCP server to expose Proxmox utilities for discovery, lifecycle management, networking, snapshots, metrics, and orchestration. With a local stdio-based server you can start it from Python or via a console script, then control Proxmox resources through MCP-compatible clients.

How to use

You interact with the MCP Proxmox server by starting a local, stdio-based MCP server and connecting your MCP client (Cursor, Claude, or another MCP client) to it. Use the available MCP tools to discover Proxmox resources, manage VMs/LXCs, handle images, templates, backups, and perform orchestration tasks. The server prints protocol data to stdout and logs to stderr, and it reads its configuration from environment variables or an .env file.

How to install

# Prerequisites
- Python 3.8+
- Virtual environment support

# Clone the project
git clone https://github.com/bsahane/mcp-proxmox.git
cd mcp-proxmox

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Upgrade pip and install dependencies
python -m pip install -U pip
pip install -r requirements.txt

# (Optional) install the package locally in editable mode
pip install -e .

Configure environment and run

cp .env.example .env

Then edit the .env values to point to your Proxmox instance and credentials. Example keys you will set:

PROXMOX_API_URL="https://proxmox.example.com:8006"
PROXMOX_TOKEN_ID="root@pam!mcp-proxmox"
PROXMOX_TOKEN_SECRET="<secret>"
PROXMOX_VERIFY="true"
PROXMOX_DEFAULT_NODE="pve"
PROXMOX_DEFAULT_STORAGE="local-lvm"
PROXMOX_DEFAULT_BRIDGE="vmbr0"

Notes:

• Use an API token with appropriate ACLs; discovery can use a broad role, while lifecycle operations should use a more restricted role on a pool.
• Using .env avoids shell history issues with special characters like ! in tokens.

Run the server in stdio mode via Python or the installed console script:

# Option 1: Python module form
source .venv/bin/activate
python -m proxmox_mcp.server

# Option 2: Installed console script
source .venv/bin/activate
proxmox-mcp

Configure in MCP clients

# Cursor portable example
{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

# Claude for Desktop portable example
{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"]
    }
  }
}

Notes on usage and configuration

• The server uses a stdio transport and prints MCP protocol data to stdout while logs go to stderr. Authentication is driven by your environment variables and/or the .env file.

Security and maintenance

• Keep API tokens and credentials restricted with least privilege. Regularly rotate tokens and keep your .env file secure. Monitor logs for unusual activity and ensure network access to Proxmox is restricted to trusted clients.

Troubleshooting

• If the server fails to start, verify that your Python environment is active and that the required packages are installed. Check for missing dependencies in the log on startup. Ensure the Proxmox API URL, token, and verify flag are correct in the .env file.

Examples

# List example commands that you might run against MCP client (not protocol payloads)
# List nodes
# proxmox-list-nodes

# Clone a template VM
# proxmox-clone-vm with appropriate JSON payload

Available tools

proxmox-list-nodes

List cluster nodes with status and resource usage

proxmox-node-status

Get detailed health information for a node

proxmox-list-vms

List virtual machines with filters by node, status, or name

proxmox-vm-info

Get details for a VM by VMID or name

proxmox-list-lxc

List LXC containers with filters

proxmox-lxc-info

Get details for an LXC container

proxmox-list-storage

List storages and capacities

proxmox-storage-content

List content of a storage (ISOs, templates, images)

proxmox-list-bridges

List node network bridges

proxmox-list-tasks

Show recent MCP-related tasks

proxmox-task-status

Check the status of a running task

proxmox-clone-vm

Clone a VM from a template or existing VMID

proxmox-create-vm

Create a new VM from ISO/template

proxmox-delete-vm

Delete a VM with optional purge

proxmox-start-vm

Power on a VM

proxmox-stop-vm

Power off a VM

proxmox-reboot-vm

Hard or soft reboot of a VM

proxmox-migrate-vm

Migrate a VM to another node

proxmox-resize-vm-disk

Grow a VM disk size

proxmox-configure-vm

Update VM resource parameters

proxmox-create-lxc

Create an LXC container from a template

proxmox-delete-lxc

Delete an LXC container

proxmox-start-lxc

Start an LXC container

proxmox-stop-lxc

Stop an LXC container

proxmox-cloudinit-set

Configure cloud-init parameters for a VM