Cursor Proxmox MCP

cursor-proxmox-mcp

Formal Cursor ↔ [Proxmox VE](https://www.proxmox.com/) 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).

Suggested agent flow

1. get_next_vmid → list_os_templates / list_isos → list_node_networks
2. provision_lxc / provision_vm (preferred one-shot) or create_lxc / create_vm → wait_for_task → start
3. create_snapshot before risky changes → update_*_config → get_guest_pending → reboot if needed
4. 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`.

# 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):

{

"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

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

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

{

"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

.\scripts\ci-local.ps1

./scripts/ci-local.sh

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

Troubleshooting

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

Configuration

Example proxmox-config/config.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](SETUP.md#1-create-a-proxmox-api-token) 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](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

.\scripts\ci-local.ps1

After adding a tool: update definitions.py, R