simple-parallels

MCP server for Parallels Desktop VM lifecycle and snapshots. Seventeen tools use fixed execFile commands (no shell, no arbitrary CLI).

Requirements: macOS, Parallels Desktop installed, prlctl (default /usr/local/bin/prlctl), Node.js 20+. start_vm, resume_vm, and restart_vm open Parallels in the background if it is not running.

Setup

npm install
npm run build
cp .cursor/mcp.json.example .cursor/mcp.json

Edit .cursor/mcp.json and replace /path/to/simple-parallels with your clone path. From the repo root:

# Clone root (paste into args, before /dist/index.js)
echo "$(pwd)/dist/index.js" | sed 's|/dist/index.js||'

# Or the full path to dist/index.js directly
echo "$(pwd)/dist/index.js"

{
  "mcpServers": {
    "simple-parallels": {
      "command": "node",
      "args": ["/path/to/simple-parallels/dist/index.js"],
      "env": {
        "PRLCTL_PATH": "/usr/local/bin/prlctl"
      }
    }
  }
}

Reload simple-parallels in Cursor Settings → MCP.

.cursor/mcp.json is gitignored; .cursor/mcp.json.example matches the config above.

Tools

Tool	Input	Description
open_parallels_desktop	—	Launch Parallels Desktop (foreground)
list_vms	—	List all VMs
list_running_vms	—	List running VMs only
show_vm_info	vm	Full VM configuration (JSON)
get_vm_status	vm	Lightweight status by name or UUID
start_vm	vm	Start a VM (auto-opens Parallels if needed)
stop_vm	vm	Gracefully stop a VM
force_stop_vm	vm	Force stop (--kill)
restart_vm	vm	Restart a VM (auto-opens Parallels if needed)
pause_vm	vm	Pause in memory
resume_vm	vm	Resume a suspended VM (auto-opens Parallels if needed)
suspend_vm	vm	Suspend to disk (saved state)
drop_vm_state	vm	Drop suspended state (--drop-state)
list_snapshots	vm	List snapshots for a VM
create_snapshot	vm, name, description?	Create a snapshot
revert_to_snapshot	vm, snapshot_id, skip_resume?	Revert to a snapshot
delete_snapshot	vm, snapshot_id, include_children?	Delete a snapshot

vm accepts a display name (e.g. Ubuntu 24.04 ARM64) or UUID (with or without {...}). Run list_vms for exact names. For snapshots, run list_snapshots first to get snapshot IDs.

Pause vs suspend: pause_vm pauses in memory; suspend_vm saves state to disk.

Auto-open: start_vm, resume_vm, and restart_vm check for the Parallels GUI (prl_client_app, not background services only). If the GUI is not running, they run open -a and wait before prlctl. Set PARALLELS_OPEN_IN_BACKGROUND=true to use open -g instead.

Configuration

Variable	Default	Description
PRLCTL_PATH	/usr/local/bin/prlctl	Path to prlctl
PARALLELS_APP_NAME	Parallels Desktop	App name for open -a
OPEN_PATH	/usr/bin/open	Path to macOS open
PGREP_PATH	/usr/bin/pgrep	Path to pgrep for process detection
PARALLELS_AUTO_OPEN_ON_VM_START	true	Set false to disable auto-open on start/resume/restart
PARALLELS_INIT_WAIT_MS	3000	Milliseconds to wait after opening Parallels
PARALLELS_OPEN_IN_BACKGROUND	false	Set true to use open -g for auto-open (no focus steal)

Out of scope

Guest exec, clone/delete VM, file transfer, arbitrary prlctl commands.