Parallels Desktop VMs

Parallels Desktop MCP

Connect your AI assistant to Parallels Desktop. pdfm-mcp lets Claude, Codex, and other MCP clients find and manage your virtual machines, run guest commands, read the screen, and automate keyboard input.

Runs locally on macOS, with a universal binary for Apple Silicon and Intel. No Go or Node installation is needed to use the released binary.

What you can do

• Find a VM, check its status, and start or stop it.
• Run commands inside Windows or Linux guests and collect their output.
• Take screenshots, read screen text, and type into the guest.
• Create snapshots, clone VMs, and automate multi-step workflows.

Once connected, try asking your assistant: “Find my Ubuntu VM and show its status” or “Take a screenshot of my running Windows VM.”

Install

You need macOS, Parallels Desktop, and an MCP client. Guest command execution also requires Parallels Tools in the guest. Screen capture and keyboard tools need a running VM.

Homebrew and the default installer use stable releases. Until the first stable release and cask are published, use the script's prerelease option below. Check the Releases page for available builds.

Homebrew

brew tap Parallels/tap
brew install --cask Parallels/tap/pdfm-mcp
pdfm-mcp --version

Install script

curl -fsSL https://raw.githubusercontent.com/Parallels/pdfm-mcp/main/scripts/install.sh | bash
/usr/local/bin/pdfm-mcp --version

The script verifies the release archive's SHA256 checksum and installs to /usr/local/bin. It asks for sudo only when the destination requires it.

To install the latest canary or beta:

curl -fsSL https://raw.githubusercontent.com/Parallels/pdfm-mcp/main/scripts/install.sh | bash -s -- --pre-release

For a particular version or a different directory, add --version <version> or --path <directory> after bash -s --.

Claude Desktop bundle

If the release includes pdfm-mcp-<version>.mcpb, download it and its matching .sha256 file from Releases. Verify it with shasum -a 256 -c pdfm-mcp-<version>.mcpb.sha256, then double-click the bundle to install. This is an alternative to configuring the binary manually below.

Connect your assistant

Your client starts the server for you. Use the binary's absolute path, since desktop apps may not inherit your terminal's PATH.

Installation	Binary path
Homebrew, Apple Silicon	/opt/homebrew/bin/pdfm-mcp
Homebrew, Intel	/usr/local/bin/pdfm-mcp
Install script, default directory	/usr/local/bin/pdfm-mcp
Install script, custom directory	<directory>/pdfm-mcp

For Homebrew, "$(brew --prefix)/bin/pdfm-mcp" resolves the right path in terminal commands. In JSON or TOML configuration, use the actual path from the table; $(brew --prefix) is not expanded there.

Claude Code

Choose the command matching your installation:

# Homebrew (Apple Silicon or Intel)
claude mcp add --transport stdio --scope user pdfm-mcp -- "$(brew --prefix)/bin/pdfm-mcp"

# Install script
claude mcp add --transport stdio --scope user pdfm-mcp -- /usr/local/bin/pdfm-mcp

Run claude mcp list to check the connection. These commands make the server available across your projects. See Claude Code's MCP setup for more options.

Codex CLI and IDE extension

Choose the command matching your installation:

# Homebrew (Apple Silicon or Intel)
codex mcp add pdfm-mcp -- "$(brew --prefix)/bin/pdfm-mcp"

# Install script
codex mcp add pdfm-mcp -- /usr/local/bin/pdfm-mcp

Run codex mcp list to confirm registration, then use /mcp in the CLI to check active servers. The CLI and IDE extension share the same MCP configuration.

If you prefer editing ~/.codex/config.toml, add:

[mcp_servers.pdfm-mcp]
command = "/opt/homebrew/bin/pdfm-mcp"

For the script installation or Intel Homebrew, change command to /usr/local/bin/pdfm-mcp. See the official Codex MCP documentation.

Plugin marketplaces

This repo is also a plugin marketplace for several assistants. Install the pdfm-mcp binary first and make sure it is on your PATH; the plugins only configure the client to launch it.

# Codex
codex plugin marketplace add Parallels/pdfm-mcp
codex plugin add pdfm-mcp@parallels

# Claude Code
claude plugin marketplace add Parallels/pdfm-mcp
claude plugin install pdfm-mcp@parallels

# Gemini CLI
gemini extensions install https://github.com/Parallels/pdfm-mcp

Cursor Teams and Enterprise admins can import this repository from Dashboard → Plugins & MCPs → Team Marketplaces.

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json and add the server to mcpServers, preserving any existing entries:

{
  "mcpServers": {
    "pdfm-mcp": {
      "command": "/opt/homebrew/bin/pdfm-mcp"
    }
  }
}

This example uses Homebrew on Apple Silicon. For the script installation or Intel Homebrew, change command to /usr/local/bin/pdfm-mcp. Restart Claude Desktop after saving.

VS Code / GitHub Copilot

Add the server to .vscode/mcp.json in your project, preserving any existing servers:

{
  "servers": {
    "pdfm-mcp": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/pdfm-mcp"
    }
  }
}

For the script installation or Intel Homebrew, change command to /usr/local/bin/pdfm-mcp. Run MCP: List Servers from the Command Palette to start the server and check its status. See VS Code's MCP setup.

Available tools

By default, your assistant can work with all local VMs. Tools that target a VM accept its UUID or exact name. To restrict the server to one VM, add --vm-id "My VM" to its launch arguments.

Tool	What it does
parallels_list_vms	List your VMs and their details.
parallels_search_vms	Find VMs by part of their name or UUID, optionally filtering by state.
parallels_vm_info	Get detailed information about one VM.
parallels_vm_start, parallels_vm_resume	Start or resume a VM.
parallels_vm_pause, parallels_vm_suspend	Pause execution or save the VM's running state.
parallels_vm_stop, parallels_vm_restart	Stop or gracefully restart a VM.
parallels_vm_reset, parallels_vm_reset_uptime	Hard-reset a VM or reset its uptime counter.
parallels_vm_capture	Take a screenshot of the VM.
parallels_vm_observe	Read screen text, find text, or report changes using local OCR.
parallels_vm_exec	Run a guest command and return its exit code and output.
parallels_vm_exec_start, parallels_vm_exec_result, parallels_vm_exec_cancel	Start, monitor, or cancel a background command job.
parallels_vm_type, parallels_vm_send_key	Type text or send keys and shortcuts to the guest.
parallels_vm_sequence	Run a workflow of tool calls, waits, and checks in one request.
parallels_vm_snapshot_create, parallels_vm_snapshot_list	Create checkpoints and browse a VM's snapshots.
parallels_vm_snapshot_switch, parallels_vm_snapshot_delete	Restore a checkpoint or delete a snapshot.
parallels_vm_clone	Create a copy of a VM.
parallels_vm_set	Change a VM's configuration (CPU, memory, boot, sharing, security and more — see the tool's own field descriptions).
parallels_vm_device_add	Add a device (hard drive, optical drive, network adapter, serial/parallel port, sound card, USB support).
parallels_vm_device_set	Modify, enable/disable or hot connect/disconnect an existing device.
parallels_vm_device_del	Remove a device; optionally destroy a virtual hard-drive image (confirmation-gated).
parallels_vm_delete	Permanently delete a VM and its files; requires explicit confirmation.
parallels_vm_reclaim_disk	Estimate or reclaim unused VM disk space.
parallels_vm_encrypt, parallels_vm_decrypt, parallels_vm_change_encryption_password	Manage VM encryption and its password.

See the tool reference for arguments, limits, and automation examples.

Choose what your assistant can access

Add launch arguments to limit access:

• --read-only: expose observation tools for inspecting VMs and their screens.
• --vm-id "My VM": target one VM.
• --allow-vms "My VM,Another VM": restrict access to selected VMs.
• --allow-tools / --deny-tools: expose or hide specific tools.

For example, add "args": ["--read-only", "--vm-id", "My VM"] beside command in a JSON client configuration. In Codex TOML, use args = ["--read-only", "--vm-id", "My VM"].

Screenshots, recognized text, command output, and tool arguments reach your MCP client and its model provider. VM deletion, snapshot rollback, guest commands, and encryption can change or destroy data; review those actions before approving them.

Release builds can collect anonymised tool usage telemetry. To opt out, set PDFM_MCP_TELEMETRY_DISABLED=true in your server's environment. See configuration and privacy for all settings.

Update or uninstall

With Homebrew:

brew upgrade --cask pdfm-mcp
brew uninstall --cask pdfm-mcp

With the install script:

# Update to the latest stable release
curl -fsSL https://raw.githubusercontent.com/Parallels/pdfm-mcp/main/scripts/install.sh | bash -s -- --update

# Uninstall
curl -fsSL https://raw.githubusercontent.com/Parallels/pdfm-mcp/main/scripts/install.sh | bash -s -- --uninstall

Add --pre-release when updating a canary or beta installation, or --path <directory> if you installed to a custom directory. Remove the server from your client's MCP settings after uninstalling.

Help and contributing

Join Discord and open #pdfm-mcp, or report an issue.

To build, test, debug, or add tools, see CONTRIBUTING.md.