Proxmox VE MCP Server

A production-ready Model Context Protocol (MCP) server built with FastMCP for high-level Proxmox VE homelab and cluster automation. Rather than acting as a plain REST API wrapper, proxmox-mcp provides semantic, domain-driven orchestration capabilities for LLM agents (Claude Desktop, Cursor, Gemini CLI, etc.).

---

Table of Contents

1. Features
2. Prerequisites & Installation
3. Environment Configuration
4. MCP Client Setup
   • Claude Desktop
   • Cursor
   • Gemini CLI
   • SSE Transport Mode
5. FastMCP Catalog
   • Tools (72 Tools across 8 Domains)
   • Resources (18 Resources)
   • Prompts (14 Prompts)
6. Security & Audit Architecture
7. Development & Verification
8. Documentation Index

---

Features

• Full VM (QEMU) & LXC Container Lifecycle Management: Create, clone, start, stop, shutdown, reboot, pause, resume, migrate, and purge virtual machines and containers.
• Hardware & Resource Tuning: Dynamically update CPU cores, sockets, RAM, disk sizes, network interfaces, and storage volume bindings.
• Cloud-Init Integration: Inject user accounts, passwords, SSH keys, network configurations, and trigger ISO regeneration directly.
• Snapshot & Rollback Tree: List, create, rollback, and delete snapshots for both VMs and LXC containers.
• Multi-Step Workflows: Automated step-by-step provisioning, bulk operations across host targets, pre-backup snapshots with vzdump execution, and cluster readiness checks with automatic rollback safety.
• Enterprise-Grade Security: CIDR-based client IP whitelisting, RBAC permission scopes (READ_ONLY, OPERATOR, ADMIN), mandatory destructive operation confirmations (confirm=true), recursive sensitive payload scrubbing, and structured audit logs.

---

Prerequisites & Installation

Prerequisites

• Python 3.12+ installed on the local system.
• uv (recommended high-performance package manager) or standard pip.
• Access to a Proxmox VE (v7.x or v8.x) server over HTTPS (port 8006).

Installation via uv (Recommended)

# Clone repository
git clone https://github.com/your-org/proxmox-mcp.git
cd proxmox-mcp

# Create virtualenv and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync --all-extras

Installation via pip

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

---

Environment Configuration

Configure connection and security settings via environment variables or a .env file in the root directory:

# Proxmox VE Connection Parameters
PROXMOX_HOST=Your_IP:8006
PROXMOX_USER=User@permision
PROXMOX_PASSWORD=Password
# Or API Token authentication (recommended):
PROXMOX_TOKEN_ID=Your_Token_ID
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PROXMOX_VERIFY_SSL=false
PROXMOX_TIMEOUT=30.0
PROXMOX_MAX_RETRIES=3

# MCP Security & Authorization Settings
MCP_PERMISSION_LEVEL=operator
MCP_AUDIT_ENABLED=true
MCP_AUDIT_LOG_PATH=audit.log
MCP_ALLOWED_CLIENT_IPS=127.0.0.1/32,192.168.1.0/24

Configuration Parameters Reference

Variable	Type	Default	Description
PROXMOX_HOST	String	Required	Host address and port of Proxmox VE instance
PROXMOX_USER	String	user@Permisions	Proxmox VE user identity
PROXMOX_PASSWORD	String	""	User password for API ticket authentication
PROXMOX_TOKEN_ID	String	""	API Token ID (takes precedence if provided)
PROXMOX_TOKEN_SECRET	String	""	API Token Secret key
PROXMOX_VERIFY_SSL	Boolean	false	Verify TLS certificates
PROXMOX_TIMEOUT	Float	30.0	HTTP request timeout in seconds
PROXMOX_MAX_RETRIES	Integer	3	Maximum retry attempts on transient network errors
MCP_PERMISSION_LEVEL	Enum	operator	Baseline permission scope (read_only, operator, admin)
MCP_AUDIT_ENABLED	Boolean	true	Enable JSON lines structured audit logging
MCP_AUDIT_LOG_PATH	Path	audit.log	Path to append structured audit records
MCP_ALLOWED_CLIENT_IPS	String	""	Comma-separated CIDR subnets allowed to execute MCP commands

---

MCP Client Setup

Claude Desktop

Add the server configuration to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "proxmox-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/proxmox-mcp",
        "run",
        "proxmox-mcp"
      ],
      "env": {
        "PROXMOX_HOST": "Your_IP:8006",
        "PROXMOX_USER": "user@permission",
        "PROXMOX_PASSWORD": "Password",
        "PROXMOX_VERIFY_SSL": "false",
        "MCP_PERMISSION_LEVEL": "operator"
      }
    }
  }
}

Cursor

Add to your project .cursor/mcp.json or Global MCP Settings:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/username/DEV/proxmox-mcp",
        "run",
        "proxmox-mcp"
      ],
      "env": {
        "PROXMOX_HOST": "Your_IP:8006",
        "PROXMOX_TOKEN_ID": "user@permission!mcp_token",
        "PROXMOX_TOKEN_SECRET": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}

Gemini CLI

Configure gemini MCP extension in settings or execution config:

{
  "mcpServers": {
    "proxmox-automation": {
      "command": "python",
      "args": [
        "-m",
        "proxmox_mcp.main"
      ],
      "cwd": "/opt/proxmox-mcp",
      "env": {
        "PROXMOX_HOST": "Your_IP:8006:8006",
        "PROXMOX_USER": "user@permission",
        "PROXMOX_PASSWORD": "Password"
      }
    }
  }
}

SSE Transport Mode

For standalone remote daemon deployment via Server-Sent Events (SSE):

# Start FastMCP server in SSE mode on port 8000
fastmcp run src/proxmox_mcp/main.py --transport sse --port 8000

---

FastMCP Catalog

Tools

1. QEMU Virtual Machine Domain (vm)

Tool Name	Scope	Confirm?	Description
list_vms	READ_ONLY	No	List VMs across cluster or specific node
vm_status	READ_ONLY	No	Retrieve detailed status for a specific VM
vm_config	READ_ONLY	No	Inspect hardware and operational config
create_vm	OPERATOR	No	Create new QEMU virtual machine
clone_vm	OPERATOR	No	Clone existing VM or template
delete_vm	ADMIN	Yes	Purge VM and associated storage volumes
start_vm	OPERATOR	No	Power on virtual machine instance
stop_vm	OPERATOR	Yes	Force stop virtual machine process
shutdown_vm	OPERATOR	Yes	Graceful OS shutdown with timeout
reboot_vm	OPERATOR	Yes	Graceful OS reboot sequence
pause_vm	OPERATOR	No	Pause execution (suspend-to-RAM)
resume_vm	OPERATOR	No	Resume execution of paused VM
suspend_vm	OPERATOR	No	Suspend VM state to storage disk
template_vm	OPERATOR	No	Convert VM into immutable template
update_cpu_vm	OPERATOR	No	Reconfigure CPU cores, sockets, NUMA settings
update_memory_vm	OPERATOR	No	Hotplug or adjust allocated RAM memory
resize_vm	OPERATOR	No	Expand virtual disk volume size
add_disk_vm	OPERATOR	No	Attach additional storage disk volume
remove_disk_vm	ADMIN	Yes	Detach and remove storage disk volume
move_disk_vm	OPERATOR	No	Relocate disk volume to target storage pool
update_network_vm	OPERATOR	No	Reconfigure virtual network interface card
configure_cloudinit_vm	OPERATOR	No	Set Cloud-Init user, password, SSH key, IP
regenerate_cloudinit_vm	OPERATOR	No	Trigger Cloud-Init ISO image regeneration
list_snapshots_vm	READ_ONLY	No	List snapshot tree for target VM
create_snapshot_vm	OPERATOR	No	Create named point-in-time VM snapshot
rollback_snapshot_vm	ADMIN	Yes	Restore VM state to target snapshot
delete_snapshot_vm	ADMIN	Yes	Remove target snapshot from tree
migrate_vm	ADMIN	Yes	Live or offline VM migration to target node

2. LXC Container Domain (lxc)

Tool Name	Scope	Confirm?	Description
list_containers	READ_ONLY	No	List LXC containers on cluster or node
container_status	READ_ONLY	No	Get detailed container runtime state
container_config	READ_ONLY	No	Inspect LXC container configuration
create_container	OPERATOR	No	Provision new LXC container
clone_container	OPERATOR	No	Clone existing container instance
delete_container	ADMIN	Yes	Destroy LXC container permanently
start_container	OPERATOR	No	Start LXC container execution
stop_container	OPERATOR	Yes	Hard stop LXC container
shutdown_container	OPERATOR	Yes	Graceful container shutdown
restart_container	OPERATOR	Yes	Reboot LXC container
template_container	OPERATOR	No	Convert LXC container into template
update_hostname_lxc	OPERATOR	No	Update container hostname
update_dns_lxc	OPERATOR	No	Update search domain and DNS nameservers
set_container_password	OPERATOR	No	Set root user password
inject_ssh_key_lxc	OPERATOR	No	Append public SSH keys for root access
resize_rootfs_lxc	OPERATOR	No	Expand container root filesystem disk
update_memory_lxc	OPERATOR	No	Adjust RAM and swap limits
update_cpu_lxc	OPERATOR	No	Adjust CPU cores and execution limits
list_mount_points	READ_ONLY	No	List attached storage mount points
add_bind_mount	OPERATOR	No	Attach host bind mount to container
remove_bind_mount	ADMIN	Yes	Detach host bind mount point
enable_nesting_lxc	OPERATOR	No	Enable nesting feature for Docker support
enable_keyctl_lxc	OPERATOR	No	Enable keyctl subsystem inside container
enable_fuse_lxc	OPERATOR	No	Mount FUSE filesystems inside container
list_snapshots_lxc	READ_ONLY	No	List snapshot tree for LXC container
create_snapshot_lxc	OPERATOR	No	Create named LXC container snapshot
rollback_snapshot_lxc	ADMIN	Yes	Revert container state to snapshot
delete_snapshot_lxc	ADMIN	Yes	Remove snapshot from container tree

3. Support Domains (cluster, nodes, storage, tasks)

Tool Name	Domain	Scope	Description
cluster_health	cluster	READ_ONLY	Evaluate quorum, node state, and storage health
cluster_resources	cluster	READ_ONLY	Summarize cluster-wide virtual resources
list_nodes	nodes	READ_ONLY	Get overview of cluster node members
node_status	nodes	READ_ONLY	CPU, memory, uptime, kernel details for node
list_storage	storage	READ_ONLY	List available cluster storage pools
storage_content	storage	READ_ONLY	Query storage volume contents (ISO, backup, disk)
storage_status	storage	READ_ONLY	Disk capacity and usage statistics for pool
recent_tasks	tasks	READ_ONLY	Query recent cluster background task logs
task_status	tasks	READ_ONLY	Check completion state for specific UPID

4. Workflows Domain (workflows)

Tool Name	Scope	Confirm?	Description
run_provisioning_workflow	OPERATOR	No	Provision VM/LXC with automated rollback on step failure
run_bulk_operation	OPERATOR	Optional	Perform batch actions (start, stop, reboot) across resource tags
run_backup_flow	OPERATOR	No	Storage pre-check, pre-backup snapshot, vzdump execution, cleanup
run_cluster_check	READ_ONLY	No	Cluster readiness assessment (quorum, disk thresholds, tasks)

5. Security Domain (security)

Tool Name	Scope	Confirm?	Description
check_client_ip	READ_ONLY	No	Test client IP against configured CIDR whitelist
audit_security_rules	READ_ONLY	No	Audit current RBAC policy and active security rules
get_security_summary	READ_ONLY	No	Retrieve high-level runtime security metrics summary

---

Resources

Contextual data endpoints read by LLM reasoning engines:

Resource URI	Scope	Description
cluster://summary	READ_ONLY	Cluster member and total resource summary
cluster://health	READ_ONLY	Real-time cluster health and quorum evaluation
node://{node}/status	READ_ONLY	CPU, RAM, and hardware metrics for host node
node://{node}/storage	READ_ONLY	Storage pool bindings on specific node
storage://{node}/summary	READ_ONLY	Storage volume allocation metrics
vm://{node}/{vmid}/status	READ_ONLY	Live runtime metrics for virtual machine
vm://{node}/{vmid}/config	READ_ONLY	Hardware specification and flags for VM
vm://{node}/{vmid}/snapshots	READ_ONLY	Snapshot hierarchy for VM
lxc://{node}/{vmid}/status	READ_ONLY	Live runtime metrics for LXC container
lxc://{node}/{vmid}/config	READ_ONLY	Container config parameters
lxc://{node}/{vmid}/snapshots	READ_ONLY	Snapshot hierarchy for container
container://{node}/{vmid}/status	READ_ONLY	Alias for LXC container status
container://{node}/{vmid}/config	READ_ONLY	Alias for LXC container config
container://{node}/{vmid}/snapshots	READ_ONLY	Alias for LXC container snapshots
task://{node}/{upid}/log	READ_ONLY	Historical operational logs for Proxmox UPID
security://status	READ_ONLY	Runtime security engine status
security://policy	READ_ONLY	Active security settings and permission thresholds
security://audit_summary	READ_ONLY	Total audit records count and operation metrics

---

Prompts

Interactive user prompt templates guiding complex workflows:

Prompt Name	Target Workflow	Description
provision_vm	VM Domain	Step-by-step guided provisioning template for QEMU VM
vm_snapshot_workflow	VM Domain	Safety-first guidance for VM snapshot creation and rollback
cloudinit_config	VM Domain	Cloud-Init setup, user creation, and ISO drive binding
provision_container	LXC Domain	Container setup checklist with unprivileged & nesting checks
lxc_troubleshooting	LXC Domain	Diagnostics guide for broken or unstartable containers
lxc_snapshot_workflow	LXC Domain	Container snapshot lifecycle management checklist
cluster_diagnostics	Cluster Domain	Comprehensive health, quorum, and network audit guide
node_diagnostics	Node Domain	Host performance tuning and resource saturation checklist
storage_inspection	Storage Domain	Pool capacity utilization and volume cleanup guide
task_troubleshooting	Task Domain	UPID task log parsing and failure root cause analysis
workflow_selection	Workflows Domain	Decision tree for choosing multi-step workflow routines
guided_provisioning	Workflows Domain	Interactive assistant for multi-tier stack deployments
security_audit	Security Domain	Review active permissions, CIDR rules, and audit logs
ip_permission_check	Security Domain	Verify IP access rights and privilege boundaries

---

Security & Audit Architecture

1. RBAC Permission Enforcement: Every tool execution is validated against the configured MCP_PERMISSION_LEVEL (read_only, operator, admin).
2. CIDR IP Whitelisting: If MCP_ALLOWED_CLIENT_IPS is configured, client incoming IP addresses are validated against allowed subnets before processing requests.
3. Destructive Operation Shield: High-risk actions (delete_vm, stop_vm, remove_disk_vm, rollback_snapshot_vm, delete_container, etc.) require explicit confirm=true parameters to prevent accidental execution.
4. Data Scrubbing: All audit payloads and logs are recursively scrubbed to sanitize passwords, tokens, tickets, and secrets (scrub_payload).
5. Structured Audit Trail: Detailed JSON logs are persisted containing execution timestamp, tool name, client context, parameter payload (scrubbed), execution duration, and Proxmox UPID task references.

---

Development & Verification

Run the automated quality assurance suite before making contributions:

# 1. Execute Unit & Integration Test Suite
pytest -v

# 2. Run Static Code Linting & Formatting Analysis
ruff check .

# 3. Run Strict Static Type Checking
mypy src tests

---

Documentation Index

For complete technical specifications, architectural diagrams, and security models, inspect the files in docs/:

• 01 — Architecture Overview
• 02 — Proxmox HTTP Client
• 03 — Pydantic Models Catalog
• 04 — QEMU VM Domain
• 05 — LXC Container Domain
• 06 — Support Domains (Cluster, Node, Storage, Task)
• 07 — Security & Audit System
• 08 — FastMCP Components Reference
• 09 — Automation Workflows
• 10 — Testing & QA Strategy
• 11 — Implementation Roadmap
• 12 — Development Conventions

---

License

Distributed under the MIT License. See LICENSE for details.