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.

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.

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.