# Proxmox VE MCP Server

[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-0.4%2B-green.svg)](https://github.com/jlowin/fastmcp)
[![Version](https://img.shields.io/badge/version-1.0.0-informational.svg)](pyproject.toml)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Type Checked: MyPy](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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](#features)
2. [Prerequisites & Installation](#prerequisites--installation)
3. [Environment Configuration](#environment-configuration)
4. [MCP Client Setup](#mcp-client-setup)
   - [Claude Desktop](#claude-desktop)
   - [Cursor](#cursor)
   - [Gemini CLI](#gemini-cli)
   - [SSE Transport Mode](#sse-transport-mode)
5. [FastMCP Catalog](#fastmcp-catalog)
   - [Tools (72 Tools across 8 Domains)](#tools)
   - [Resources (18 Resources)](#resources)
   - [Prompts (14 Prompts)](#prompts)
6. [Security & Audit Architecture](#security--audit-architecture)
7. [Development & Verification](#development--verification)
8. [Documentation Index](#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)

```bash
# 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`

```bash
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:

```ini
# 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`

```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:

```json
{
  "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:

```json
{
  "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):

```bash
# 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:

```bash
# 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/`](docs/README.md):

- [01 — Architecture Overview](docs/01-architecture.md)
- [02 — Proxmox HTTP Client](docs/02-proxmox-client.md)
- [03 — Pydantic Models Catalog](docs/03-models.md)
- [04 — QEMU VM Domain](docs/04-vm-domain.md)
- [05 — LXC Container Domain](docs/05-lxc-domain.md)
- [06 — Support Domains (Cluster, Node, Storage, Task)](docs/06-support-domains.md)
- [07 — Security & Audit System](docs/07-security-audit.md)
- [08 — FastMCP Components Reference](docs/08-mcp-components.md)
- [09 — Automation Workflows](docs/09-workflows.md)
- [10 — Testing & QA Strategy](docs/10-testing.md)
- [11 — Implementation Roadmap](docs/11-roadmap.md)
- [12 — Development Conventions](docs/12-conventions.md)

---

## License

Distributed under the MIT License. See `LICENSE` for details.