You can manage Proxmox virtualization resources through an enhanced MCP server that exposes a rich set of REST-like endpoints and local streaming interfaces. This server enables full VM and container lifecycle control, snapshots, backups, ISO/template handling, and OpenAPI integration for external tooling and Open WebUI workflows.

How to use

You interact with the MCP server by running it locally or connecting via a configured MCP client. Use the available tools and endpoints to create, start, stop, and delete virtual machines, manage LXC containers, take and restore snapshots, perform backups, and handle installation media and templates. You can also leverage OpenAPI REST endpoints for integration with external applications or web UIs, and you can connect through standard IO or transport methods such as SSE or STREAMABLE.

How to install

Prerequisites include a Python 3.9+ environment, Git, and access to a Proxmox server with API token credentials. You should also have the UV package manager installed for convenient environment setup.

# Prerequisites
- Python 3.9+ installed
- Git available
- UV package manager recommended
- Proxmox server hostname or IP
- Proxmox API token ready

# Quick Install (Recommended)
1. Clone the project

git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git

2. Change into the repository

cdd ProxmoxMCP-Plus

3. Create and activate a virtual environment

uv venv source .venv/bin/activate # Linux/macOS

OR

.\.venv\Scripts\Activate.ps1 # Windows

4. Install dependencies

uv pip install -e ".[dev]"

5. Create configuration

mkdir -p proxmox-config cp proxmox-config/config.example.json proxmox-config/config.json

6. Edit the configuration at proxmox-config/config.json to supply your Proxmox host, token, and logging preferences.

{ "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" }, "mcp": { "host": "127.0.0.1", "port": 8000, "transport": "STDIO" } }

7. Verify installation

python -c "import proxmox_mcp; print('Installation OK')"

8. Run the MCP server in development mode

python -m proxmox_mcp.server

9. Run tests (optional)

pytest

## Configuration

You configure access to Proxmox via an API token in Proxmox, then supply connection details to the MCP server. The example configuration shows how to set up the Proxmox host, API token, logging, and MCP transport. You can choose the transport as STDIO, SSE, or STREAMABLE to suit your client.

{ "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" }, "mcp": { "host": "127.0.0.1", "port": 8000, "transport": "STDIO" } }

## Security and OpenAPI deployment

This MCP server provides token-based authentication and OpenAPI REST endpoints for integration with external tools and Open WebUI workflows. You can deploy the OpenAPI service separately to expose the MCP endpoints over HTTP.

Quick OpenAPI start (example hidden service)

Install the OpenAPI proxy if needed

pip install mcpo

Start the OpenAPI service (example script path)

./start_openapi.sh

Access endpoints

API Documentation: http://your-server:8811/docs

OpenAPI Specification: http://your-server:8811/openapi.json

Health Check: http://your-server:8811/health

## Troubleshooting and notes

If you encounter port conflicts, adjust the OpenAPI or MCP server port and update configurations accordingly. Verify Proxmox connectivity using API requests to the Proxmox server, and check the logs for details.

View logs during troubleshooting

tail -f proxmox_mcp.log

Or, for the OpenAPI service when running in Docker

docker logs proxmox-mcp-api -f

## Open WebUI and natural language creation

The server supports integration with Open WebUI and natural language VM creation requests via AI assistants. You can create VMs by asking in natural language, and the system will map requests to the create\_vm endpoint and return detailed configuration information.

## Project structure and deployment status

The project provides a modular structure with source code, tests, configuration, and tooling to manage virtualized resources. The deployment status indicates feature completion across VM and container management, snapshots, backups, ISO/template handling, OpenAPI integration, and Open WebUI integration.

## Available tools

### create\_vm

Create a new virtual machine with specified resources such as node, vmid, name, cpus, memory, and disk size.

### start\_vm

Start a virtual machine on the designated node.

### stop\_vm

Force stop a running virtual machine.

### shutdown\_vm

Gracefully shutdown a virtual machine.

### reset\_vm

Reset (restart) a virtual machine.

### delete\_vm

Completely delete a virtual machine.

### list\_snapshots

List all snapshots for a VM or container.

### create\_snapshot

Create a snapshot of a VM or container.

### delete\_snapshot

Delete a snapshot.

### rollback\_snapshot

Rollback a VM/container to a previous snapshot.

### list\_backups

List available backups across the cluster.

### create\_backup

Create a backup of a VM or container.

### restore\_backup

Restore a VM or container from a backup.

### delete\_backup

Delete a backup file from storage.

### list\_isos

List available ISO images across the cluster.

### list\_templates

List available OS templates for container creation.

### download\_iso

Download an ISO image from a URL to Proxmox storage.

### delete\_iso

Delete an ISO or template from storage.

### get\_nodes

List all nodes in the Proxmox cluster.

### get\_node\_status

Get detailed status of a specific node.

### get\_vms

List all VMs across the cluster.

### get\_storage

List available storage pools.

### get\_cluster\_status

Get overall cluster status and health.

### execute\_vm\_command

Execute a command in a VM's console via QEMU Guest Agent.