Cursor Proxmox MCP

Official

by hackmods · Python

Manage Proxmox VE via Cursor: QEMU, LXC, storage, HA, firewall, access.

The MCP server, io.github.hackmods/cursor-proxmox-mcp, provides an interface to manage Proxmox VE from Cursor. Its scope is described as covering QEMU, LXC, storage, HA, firewall, and access, based on the server’s available description.

🛠️ Key Features

QEMU management
LXC management
Storage management
HA (high availability) management
Firewall management
Access management

🚀 Use Cases

Managing virtual machines (QEMU) in Proxmox VE
Managing containers (LXC) in Proxmox VE
Operating Proxmox VE storage and related configuration
Configuring HA behavior for Proxmox VE
Managing firewall rules and access controls

⚡ Developer Benefits

Targets Proxmox VE administration workflows from within Cursor
Clear feature coverage across common Proxmox VE areas (QEMU, LXC, storage, HA, firewall, access)

⚠️ Limitations

Source data does not list tools, endpoints, topics, or any readme excerpt.

Topics

cursorlxcmcpproxmoxpythonqemuai-toolscursor-aihomelabmcp-servervirtualization

README.md13 KBView on GitHub

cursor-proxmox-mcp

Formal Cursor ↔ Proxmox VE MCP integration — 212 tools covering QEMU VMs (incl. guest-agent network/file/guest-info/fsfreeze + bootstrap_cloudinit_vm / provision_vm + qm_set_vm), LXC (incl. provision_lxc, bootstrap_docker_lxc, crun Path B, DNS/SSH helpers, deploy_node_app), unified guest power, storage admin (incl. PBS plugin + status), cluster/tasks (incl. join), snapshots, backups, migration, HA, firewall, access control, replication, SDN write + apply, ACME order/renew, Ceph status/pools + gated OSD create/destroy, node network CRUD, console tickets/get_console_connection, and host reboot/shutdown. v1.9.0 adds optional dual-credential elevated mode (auth_write, D31) + provision_vm + Cursor day-2 auto-approve docs.

Repo: hackmods/cursor-proxmox-mcp

Docs: Setup guide · Wiki (docs/wiki/) · Publishing · Security · Contributing · API coverage · Changelog

MCP tools

Registered via tools/register.py (called from ProxmoxMCPServer._setup_tools()) — inventory locked by tools/inventory.py / tests/expected_tools.py (CI fails on drift).

Domain	Tools
Nodes	`get_nodes`, `get_node_status`, `list_node_networks` + create/update/delete + `reload_node_network`, `get_node_subscription`, `list_node_certificates`, `get_node_report`, `list_node_services`, `get_node_time`, `wake_node`, `reboot_node` / `shutdown_node` (`confirm=<node>`)
Cluster / tasks	`get_cluster_status`, `get_next_vmid`, `get_task_status`, `list_tasks`, `wait_for_task`, `get_version`, `get_mcp_capabilities`, `get_cluster_resources`, `get_cluster_log`, `get_cluster_options`, `get_cluster_join_info`, `join_cluster` (`confirm=JOIN`)
QEMU	lifecycle + config (ISO/cloud-init/net/onboot/tags/description; optional `wait=true`) + `get_vm_network` / `get_vm_guest_info` / `fsfreeze_vm` / `fsthaw_vm` / `push_to_vm` / `pull_from_vm` (guest agent) + `bootstrap_cloudinit_vm` / `provision_vm` (one-shot create or clone→CI→IP) + `qm_set_vm` + `get_vm_status`, `get_vm_rrd_data`, console tickets
LXC	lifecycle + config + suspend/resume (CRIU warn) + `get_lxc_status` / `get_lxc_network` / `get_lxc_rrd_data` + VNC/SPICE/termproxy; `ssh_public_keys` / `docker_ready` / `nameserver` / `wait` / `onboot` / `description` / `tags` on create; `provision_lxc` (one-shot create→start→IP→SSH) / `bootstrap_docker_lxc` / `prepare_lxc_for_docker` (`docker_mode=auto
Guest (unified)	`start/stop/shutdown/reboot/delete_guest`, `get_guest_status`, `get_guest_pending`, `move_guest_disk`, `get_console_connection` (`guest_type`)
Snapshots / Backups	snapshot CRUD/rollback; one-shot backup CRUD; scheduled `list/create/delete_backup_job`
Storage	list, content, `list_os_templates`, `list_isos`, download-url, definition CRUD; PBS via `create_storage(type=pbs)` + `get_pbs_storage_status`
Migrate / HA	`migrate_guest`; HA groups + resources CRUD
Firewall	cluster + guest rules/options; aliases; IP sets + CIDR members; macros
Access	users, groups, roles, ACL, tokens, `get_permissions`, `get_token_permissions`
Replication	list/status/run/create/update/delete jobs
SDN	zones/vnets/subnets CRUD + list controllers/ipams/dns + `apply_sdn`
ACME	list + create account/plugin, delete plugin, `order_acme_certificate` / `renew_acme_certificate`
Ceph	status, list pools/OSDs/MONs/MGRs, pool CRUD; gated OSD: `list_node_disks` → `propose_ceph_osd` → `create_ceph_osd`/`destroy_ceph_osd` (typed confirm; create defaults `dry_run=true`)
Pools	list/get/create/update/delete

Suggested agent flow

get_next_vmid → list_os_templates / list_isos → list_node_networks
provision_lxc / provision_vm (preferred one-shot) or create_lxc / create_vm → wait_for_task → start
create_snapshot before risky changes → update_*_config → get_guest_pending → reboot if needed
migrate_guest / HA / firewall / access / replication as needed

Guest type unknown? Prefer unified tools (start_guest, stop_guest, shutdown_guest, reboot_guest, delete_guest, get_guest_status) with guest_type=qemu|lxc. Parallel *_vm / *_lxc names stay for existing prompts.

Installation

Prerequisites

uv (recommended) or Python 3.10+
Proxmox API token

Path 1 — uvx (recommended)

PyPI package name is cursor-proxmox-mcp (console scripts: cursor-proxmox-mcp, plus aliases proxmox-mcp-server / proxmox-mcp).

Note: The unrelated PyPI project proxmox-mcp-server is a different codebase. Always install cursor-proxmox-mcp.

bash

# Install uv if needed:  pip install uv   OR   winget install astral-sh.uv

# After PyPI publish (GitHub Release → publish.yml):
uvx cursor-proxmox-mcp

# From a local checkout (dev / before first publish):
uvx --from . cursor-proxmox-mcp

Cursor MCP (published package — no checkout):

json

{
  "mcpServers": {
    "proxmox": {
      "command": "uvx",
      "args": ["cursor-proxmox-mcp"],
      "env": {
        "PROXMOX_MCP_CONFIG": "C:/Users/YOU/proxmox-config/config.json"
      }
    }
  }
}

From a local checkout, use "args": ["--from", "C:/Users/YOU/Projects/cursor-proxmox-mcp", "cursor-proxmox-mcp"] instead.

Why uvx: it resolves dependencies into an isolated ephemeral env so Cursor does not depend on a hand-managed venv/PYTHONPATH.

Path 2 — uv from source

bash

git clone https://github.com/hackmods/cursor-proxmox-mcp.git
cd cursor-proxmox-mcp
uv venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
uv pip install -e ".[dev]"
cp proxmox-config/config.example.json proxmox-config/config.json
# Edit host + token, then:
uv run cursor-proxmox-mcp

Path 3 — pip fallback

bash

python -m venv .venv
# activate venv
pip install -e ".[dev]"
# optional OpenAPI bridge: pip install -e ".[openapi]"
$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"   # PowerShell
python -m proxmox_mcp.server

Cursor MCP (direct Python — use absolute paths):

json

{
  "mcpServers": {
    "proxmox": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"],
      "cwd": "C:/Users/YOU/Projects/cursor-proxmox-mcp",
      "env": {
        "PROXMOX_MCP_CONFIG": "C:/Users/YOU/Projects/cursor-proxmox-mcp/proxmox-config/config.json",
        "PYTHONPATH": "C:/Users/YOU/Projects/cursor-proxmox-mcp/src"
      }
    }
  }
}

Restart the proxmox MCP server in Cursor after pulling new tools. Manual launchers: start.bat (Windows) / start.sh (Unix) — prefer uvx cursor-proxmox-mcp in mcp.json.

Verify / local CI

powershell

.\scripts\ci-local.ps1

bash

./scripts/ci-local.sh

Runs: editable install → entrypoint smoke → ruff → pytest → inventory floor (≥100 tools).

Troubleshooting

Symptom	Fix
`spawn uvx ENOENT`	Install uv (`pip install uv` or `winget install astral-sh.uv`), then restart Cursor
`ModuleNotFoundError: proxmox_mcp`	Use uvx/`uv run`, or set `PYTHONPATH=.../src` for plain python
`PROXMOX_MCP_CONFIG ... must be set`	Point env at `proxmox-config/config.json` (absolute path)
Auth OK but empty data / odd 403	Privilege Separation Yes without token ACL — see SETUP.md
403 on HA / firewall / `keyctl`	Token needs elevated role; prefer scoped `mcp@pve` over `root@pam` when possible
Tools missing in Cursor	Restart MCP server after git pull

First-time cluster wiring (token, privsep, Cursor JSON, example prompts): SETUP.md. LXC shell / runtime IP needs opt-in host SSH (authorized_keys, optional host_overrides, reload MCP): SETUP.md — SSH for LXC exec.

Configuration

Example proxmox-config/config.json:

json

{
  "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",
    "verbose": false,
    "tool_calls": true
  }
}

Tool invocations are audited to the log file as tool_call name=… ok=… duration_ms=… (secrets redacted). Set verbose: true or env PROXMOX_MCP_VERBOSE=1 for richer diagnostics without urllib3 spam. Details: proxmox-config/README.md — Logging.

Create the token in Proxmox UI: Datacenter → Permissions → API Tokens. See SETUP.md — API token & Privilege Separation for the full walkthrough.

Privilege Separation: leave Yes (default) and grant ACLs to the token (user@realm!tokenid). Setting it to No makes the token inherit the user’s full permissions (common lab shortcut; larger blast radius if leaked). Grant roles matching the tools you use (PVEAuditor, PVEVMAdmin, Datastore.*, Sys.Audit/Sys.Modify for HA/firewall/access).

Prefer "token_value": "${PROXMOX_TOKEN_VALUE}" in config and set the env var in Cursor MCP config so secrets stay out of the JSON file.

Security

This server can create/delete guests, change firewall/ACL, and run guest commands. Treat the API token like production infra credentials. Full policy: SECURITY.md.

Features

Token auth via proxmoxer (JSON config + optional ${ENV} secret interpolation)
Structured tool_call audit logging (redacted) + verbose / env log overrides
Full guest lifecycle, snapshots, vzdump backups
Storage content + definition CRUD + URL download
Cluster HA, firewall (rules/aliases/ipsets), access/ACL/tokens
Replication jobs, SDN write + apply, ACME order/renew, Ceph status/pools, pools
Console ticket mint + get_console_connection (VNC/SPICE/termproxy) — no websocket proxy (D6)
PBS as PVE storage plugin (not full PBS product admin); node network CRUD + reload
uvx / uv / pip / Docker (GHCR) install paths; optional .[openapi] for mcpo
Local + GitHub CI (ruff + pytest + coverage + inventory + design invariants)

Closed non-goals (not missing — D30)

Do not treat these as planned gaps: long-lived VNC/SPICE websocket proxy (tickets only — D6), full PBS product admin, or ungated Ceph OSD/MON/MGR create/destroy. Gated OSD tools are shipped; MON/MGR lifecycle stays on Ceph/PVE tooling.

Development

powershell

.\scripts\ci-local.ps1

After adding a tool: update definitions.py, README table, .cursor/research/proxmox-api-coverage.md, .cursor/research/next-expansion.md (if closing a planned row), and tests/expected_tools.py.

Status

Formal multi-domain Proxmox API coverage (212 tools)
Phase B + Phase D agent QOL tools
Phase F LXC day-2 + Phase F.1 VM network/push + create wait opt-in
Phase C light: node reboot/shutdown + cluster join (typed confirm)
Phase C remainder: SDN write / ACME / Ceph pools / console helper / PBS storage / node net CRUD
Gated Ceph OSD create/destroy (confirm + dry-run default)
v1.0 security hardening, code-design audit, full test suite
uvx cursor-proxmox-mcp + PyPI/GHCR release workflow
Local + GitHub CI with coverage + design invariants

License

MIT

Acknowledgments

Based on ProxmoxMCP / canvrno/ProxmoxMCP. Extended for Cursor IDE as a formal Proxmox VE integration.

Install

Configuration

Environment variables

PROXMOX_MCP_CONFIGrequired

Absolute path to Proxmox MCP config.json (host, token, SSL).

PROXMOX_TOKEN_VALUEsecret

API token secret when config uses ${PROXMOX_TOKEN_VALUE}.

PROXMOX_MCP_VERBOSE

Set to 1 for verbose tool_call detail (also bumps INFO→DEBUG).

PROXMOX_MCP_LOG_LEVEL

Override logging.level (DEBUG|INFO|WARNING|ERROR).

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "cursor-proxmox-mcp": {
      "command": "uvx",
      "args": [
        "cursor-proxmox-mcp"
      ],
      "env": {
        "PROXMOX_MCP_CONFIG": "<YOUR_PROXMOX_MCP_CONFIG>",
        "PROXMOX_TOKEN_VALUE": "<YOUR_PROXMOX_TOKEN_VALUE>",
        "PROXMOX_MCP_VERBOSE": "<YOUR_PROXMOX_MCP_VERBOSE>",
        "PROXMOX_MCP_LOG_LEVEL": "<YOUR_PROXMOX_MCP_LOG_LEVEL>"
      }
    }
  }
}