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

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

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