cursor-proxmox-mcp

Formal Cursor ↔ Proxmox VE MCP integration — 211 tools covering QEMU VMs (incl. guest-agent network/file/guest-info/fsfreeze + bootstrap_cloudinit_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.8.0 adds carefully gated Ceph OSD ops (r18).

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

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

.\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 (211 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.