ProxmoxMCP Plus

You have a Python-based MCP server that gives you direct, OpenAPI-enabled control over Proxmox virtualization. It provides complete VM lifecycle management, container handling, OpenWebUI integration, and production-grade security, letting you manage VMs, containers, storage, and cluster health via REST endpoints or via a local runtime. This guide shows you how to use, install, configure, and operate ProxmoxMCP Plus so you can build automation, integrate with Open WebUI, and run in production with confidence.

How to use

You interact with ProxmoxMCP Plus through its MCP endpoints or by running the local server and using the OpenAPI service. You can create VMs with specific resources, power them on and off, manage LXC containers, inspect nodes and storage, run commands inside VMs, and trigger backups or replication. Use the REST API endpoints to perform actions and retrieve live status, then fold those results into your automation scripts or UI integrations.

How to install

Prerequisites you need on your host before you begin:

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

1. Clone the project repository
2. Create and activate a Python virtual environment
3. Install dependencies
4. Create and edit the MCP configuration file
5. Verify the installation and run the server tests (optional)

# 1. Clone repository
git clone https://github.com/davidpius95/guildserver-proxmox-mcpserver.git
cd guildserver-proxmox-mcpserver

# 2. Create and activate virtual environment
uv venv
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# 3. Install dependencies (development dependencies if needed)
uv pip install -e ".[dev]"

# 4. Create configuration directory and copy template
mkdir -p proxmox-config
cp proxmox-config/config.example.json proxmox-config/config.json

# 5. Edit proxmox-config/config.json with your Proxmox and API token details

Additional configuration and usage notes

Configure your Proxmox API access and MCP environment by providing your Proxmox host, API token, and logging preferences as shown in the configuration example.

{
  "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"
  }
}

Security and access

Use token-based authentication to Proxmox and enable production-grade logging to monitor usage and anomalies. Keep your API tokens secure and rotate them periodically. When exposing the OpenAPI service, consider using a reverse proxy with TLS and a strong access policy.

Troubleshooting and tips

If you encounter port conflicts, configuration errors, or connectivity issues with Proxmox, verify the setup steps, check the MCP configuration, and inspect logs for clues. Common checks include ensuring the Proxmox API token is valid, the MCP config points to the correct Proxmox host, and the chosen port for the OpenAPI service is available.

Notes on deployment options

OpenAPI deployment can be run in production as REST endpoints and can be containerized with Docker or Docker Compose. You can also run the core MCP server locally in development mode for testing and automation scenarios.

Available tools

create_vm

Create a new virtual machine with a specified VMID, name, resources, and optional storage settings, returning a detailed configuration snapshot and a task ID.

delete_vm

Delete a VM either softly or forcefully, with optional confirmation and task tracking.

start_vm

Start a stopped VM on the designated Proxmox node.

stop_vm

Force stop a running VM on the designated Proxmox node.

shutdown_vm

Gracefully shut down a running VM, allowing graceful guest shutdown when possible.

reset_vm

Restart a VM to refresh its state without removing the VM configuration.

get_containers

List all LXC containers across the cluster with status information.

start_container

Start a specified LXC container.

stop_container

Stop a specified LXC container.

restart_container

Restart a container, with an option for graceful or forceful restart.

get_nodes

List all Proxmox cluster nodes with status and resource usage.

get_node_status

Retrieve detailed status for a specific node.

get_vms

List all VMs across the cluster.

get_vm_status

Get the current status of a specific VM.

get_vm_snapshots

List snapshots for a specific VM.

get_storage

List available storage pools on the cluster.

get_storage_content

List content within a storage pool on a node.

get_cluster_status

Provide overall cluster health and status information.

get_cluster_resources

Show a cluster-wide view of resource usage and capacity.

execute_vm_command

Execute a command within a VM using QEMU Guest Agent.

list_services

List system services on a node.

service_action

Start, stop, or restart a node service.

network_get

Fetch node network configuration details.

network_apply

Apply new or updated network configuration to a node.

list_updates

List available package updates on a node.

list_repositories

List APT repositories configured on a node.

get_certificates

Query TLS certificates information on the node or cluster.

list_disks

List disk devices on a node.

list_users

List MCP-managed users.

create_user

Create a new MCP user.

update_user

Update an existing MCP user.

delete_user

Delete an MCP user.

list_groups

List MCP user groups.

create_group

Create a new MCP group.

delete_group

Delete an MCP group.

list_roles

List MCP roles.

create_role

Create a new MCP role.

delete_role

Delete an MCP role.

get_acl

Get access control entries.

set_acl

Set an access control entry.

list_dc_firewall_rules

List firewall rules at the datacenter level.

add_dc_firewall_rule

Add a firewall rule at the datacenter level.

delete_dc_firewall_rule

Delete a datacenter firewall rule.

list_pools

List storage pools.

create_pool

Create a new storage pool.

delete_pool

Delete a storage pool.

vzdump

Trigger a VZDump backup job on a node.

ha_list_groups

List High Availability groups.

ha_create_group

Create a new HA group.

ha_list_resources

List resources within an HA group.

ha_add_resource

Add a resource to an HA group.

ha_delete_resource

Remove a resource from an HA group.

replication_list_jobs

List Proxmox replication jobs.

replication_create_job

Create a new replication job.

replication_delete_job

Delete a replication job.

sdn_list_zones

List SDN zones.

sdn_list_vnets

List SDN virtual networks.

ceph_status

Query Ceph status on a node.

ceph_df

Query Ceph disk usage.

vm_vncproxy

Create a VNC proxy for a VM.

vm_spiceproxy

Create a SPICE proxy for a VM.

vm_move_disk

Move a VM disk to another storage.

vm_import_disk

Import a VM disk into Proxmox.

vm_attach_disk

Attach a disk to a VM.

vm_detach_disk

Detach a disk from a VM.

delete_storage_content

Delete a storage content item (ISO/template/backup).

upload_storage_content

Upload content to storage (ISO/template/backup).

proxmox_request

Call any Proxmox API endpoint directly.