Transversals
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Transversals
Transversals is a general-purpose MCP server that lets OpenCode and Claude Code drive your own Parallels Windows 11 ARM VM (a "transversal" across Parallels). It runs PowerShell, takes screenshots, sends keyboard/mouse input, manages windows, and reads and operates the Windows UI through UI Automation.
Transversals is open source (MIT) and works only on Apple Silicon Macs with Parallels Windows 11 ARM VMs. The installer is an unsigned .pkg that you build with npm run pkg (see Development).
Requirements
Apple Silicon Mac
Parallels Desktop with
prlctl(an edition that supportsprlctl)A running Windows 11 ARM VM with Parallels Tools and a user logged in to the Windows console
Mac folder sharing available to the VM.
setupadds a temporary read-only share (transversals-provision) to copy the agent in, then removes it. If the guest can't see it, runprlctl set <vm> --shf-host on.Claude Code and/or OpenCode
The guest agent is self-contained (an exe plus four native DLLs), so the VM needs no .NET runtime. Node is bundled in the package.
Related MCP server: win-computer-use
Install
Install the package:
sudo installer -pkg transversals-<version>.pkg -target /The package is unsigned, so Gatekeeper blocks a downloaded copy on double-click. Install it with the command above, or remove the quarantine flag first (
xattr -d com.apple.quarantine transversals-<version>.pkg) and then double-click it. A package you built yourself isn't quarantined.Run setup with the VM running and logged in:
transversals setup [--vm "<name or uuid>"]--vmis optional only when you have exactly one VM. Setup:temporarily shares the agent with the VM and copies it (the exe, then the rest of the agent folder: four native DLLs) to
%LOCALAPPDATA%\transversals\agentin the guest, then removes the shareverifies the agent responds, and warns if its version differs from the host's (the bundled agent is stale)
saves the VM and agent path to the config file
creates the
transversals-baselinesnapshot if it doesn't existregisters
transversalswith Claude Code and OpenCode (skipped for a client that isn't installed;--no-registerskips both,transversals register [--client claude|opencode]does it later)
Restart Claude Code / OpenCode.
Check everything with transversals doctor. It reports PASS/FAIL/SKIP for config, VM, VM running, Parallels Tools, guest agent, and baseline snapshot. The guest agent check compares the agent's version with the host's and fails on any mismatch (including an agent that reports "unknown"); the fix is to rerun transversals setup.
Tools
All tools take the configured vmId.
Tool | Purpose |
| Get the VM's Parallels status. |
| Start the VM. |
| Run bounded PowerShell (max 8,192 characters) in the guest's interactive session. Results include |
| Capture the guest screen. Returns the image with |
| Type text, press a key chord (e.g. |
| List top-level windows with handles, titles, and owning processes. |
| Bring a window to the foreground by handle from |
| Capture a bounded UI Automation tree. |
| Find one element with a semantic locator. |
| Run an ordered, fail-fast batch of 1–50 semantic commands (find, interact, assert, wait). |
| Restore the VM to |
Click coordinates. send_input click x/y are virtual-screen pixels, not screenshot pixels. For a point (px, py) in a screenshot:
x = screen.left + px * screen.width / imageWidth
y = screen.top + py * screen.height / imageHeight (rounded to integers)Restore safety. vm_restore only ever restores the snapshot named transversals-baseline that setup created. It fails if there isn't exactly one.
Truncation. run_powershell output is capped, with the stdoutTruncated / stderrTruncated flags above. ui_snapshot is bounded by depth, node count, and response size; a truncated snapshot includes truncation metadata (e.g. reasons, includedNodes, omittedNodesAtLeast, truncatedFields).
Semantic locators match on role, name, text, value, and ancestor/descendant/sibling context, with optional fuzzy and zero-based index. No match returns NOT_FOUND. An ambiguous match returns AMBIGUOUS_MATCH with a few candidates instead of guessing. References are valid only for the current snapshot; ref: "$last" reuses the latest reference within a batch.
Live stream
transversals stream is a CLI command (not an MCP tool) that streams the guest screen as MJPEG (concatenated JPEG frames) to stdout. It uses its own prlctl exec connection, so it doesn't block MCP tool calls.
transversals stream [--fps 1-30] [--max-size 320-1920] [--quality 30-95] [--vm <name|uuid>]Option | Default | Meaning |
| 15 | Frames per second |
| 800 | Longest image edge in pixels |
| 70 | JPEG quality |
| configured VM | VM name or UUID |
transversals stream | mpv --demuxer-lavf-format=mjpeg --profile=low-latency --untimed -
transversals stream | ffplay -f mjpeg -Needs a running VM with a logged-in user and the guest agent from this version (see Upgrading).
Exits 0 on Ctrl-C/SIGTERM or when the consumer closes the pipe. Exits 1 if the first frame doesn't arrive within 10 s, if frames stall for more than 5 s, or if the relay dies.
A slow consumer gets frames dropped, never partial JPEGs.
Diagnostics go to stderr only; stdout is binary video.
The guest side stops by itself when the host goes away (stdin closed, a failed write, or a write stalled for 5 s). The host also sends a heartbeat on the agent's stdin every second, and the guest exits after 5 s without one, which covers the host or
prlctlbeing killed abruptly.On shutdown, the final flush of buffered output is bounded to 2 s.
Pacing: a capture and encode takes ~27 ms, and in the VM a short wait wakes 15–20 ms late. The stream captures a slot that is late by less than one frame period instead of skipping it. Slots missed by a whole period are still dropped, never sent as a burst, and it never runs faster than
--fps.Observed performance (not a guarantee; test VM with 4 vCPU, 2560×1402, version 0.2.2):
--fps 30gave ≈29.6 fps at ~42% of one guest core, and--fps 15gave 15.0 fps at ~24% (~135 MB at 15 fps in an earlier measurement). The ceiling is ≈37 fps (the capture time);--fpsstill maxes out at 30.
Guest agent lifecycle
The MCP server starts one agent per session over prlctl exec (NDJSON). The host says hello to each new agent, and for protocol 2 and later sends a blank keepalive line every 5 s; older agents get no keepalives. The agent exits after 30 s with no input, so it idles out 30 s after its host disappears.
Configuration
Config file: ~/Library/Application Support/transversals/config.json, with keys vmId and agentExecutable.
Environment variable | Overrides |
|
|
|
|
transversals config # show effective config (env overrides the file)
transversals config set vmId <uuid>
transversals config set agentExecutable '<guest path to Transversals.GuestAgent.exe>'Upgrading
Install the new
.pkg.Make sure no old agent is running. Setup reports "in use" otherwise. Close MCP sessions; note that the OpenCode service keeps an MCP
servealive, so you may also need to stop the agent in the guest:Get-Process Transversals.GuestAgent | Stop-Process.Rerun
transversals setup.Refresh the baseline snapshot: the existing
transversals-baselineis left unchanged and still holds the old agent, sovm_restorewould bring it back. Delete the snapshot (Parallels Snapshot Manager, orprlctl snapshot-delete <vm> --id <snapshot-id>) and rerunsetup. Setup warns about this, andtransversals doctorflags a stale agent.
transversals stream needs the guest agent from the same version. Against an older agent, a stream trips the 10 s first-frame watchdog and prints a hint.
Uninstall
transversals uninstallThis unregisters from Claude Code and OpenCode, removes %LOCALAPPDATA%\transversals from the VM (if running), offers to delete the baseline snapshot (default: no), and removes the config directory. It then prints the sudo commands that remove the package itself; run them yourself.
Troubleshooting
AGENT_UNAVAILABLE: runtransversals doctor. Usual causes: VM stopped, nobody logged in to Windows, Parallels Tools not running, or a missing/outdated agent (rerunsetup)."installed guest agent is in use" during setup: close MCP sessions using Transversals (or end
Transversals.GuestAgent.exein the guest withGet-Process Transversals.GuestAgent | Stop-Process), then rerunsetup.Guest can't see the share during setup: make sure Mac folder sharing is on (
prlctl set <vm> --shf-host on). To clear a stale share:prlctl set <vm> --shf-host-del transversals-provision."No video frame from the guest agent for 10 s" / "5 s" (
transversals stream): the guest isn't producing frames. Check that Windows is logged in and runtransversals doctor; if the agent is outdated, reruntransversals setup.Agent before 0.2.0 crashes immediately (exit 255; the Windows event log shows
wpfgfx_cor3.dllwith0xc000001d) after the VM was stopped abruptly: its single-file extraction cache may be corrupt. Upgrade to 0.2.0+, which ships the native DLLs beside the exe and no longer extracts to%TEMP%\.net. For an old agent, delete%TEMP%\.net\Transversals.GuestAgent\in the guest (no agent running) and retry; leftover folders from old agents can be deleted.SNAPSHOT_NOT_FOUND: runtransversals setupto createtransversals-baseline.SNAPSHOT_AMBIGUOUS: more than onetransversals-baselinesnapshot exists. Delete the extras in Parallels Snapshot Manager so exactly one remains.
Development
Requires Node 22 and the .NET 8 SDK.
npm install
npm run build # compile the host (tsc)
npm test # host tests (vitest)
npm run verify # tests, typecheck, build, guest tests and build
npm run guest:publish # publish the self-contained win-arm64 agent to dist/guest/win-arm64
npm run pkg # build out/transversals-<version>.pkg (unsigned, bundles Node 22 arm64)npm run pkg needs the arm64 Node 22 build and a warm npm cache (production dependencies are installed offline).
Layout:
src/: host MCP server (index.ts), CLI (cli.ts), stream relay (stream.ts), OpenCode config editing, guest-agent clientguest/: .NET guest agent (src/) and its tests (tests/). With no arguments the agent runs the NDJSON session;Transversals.GuestAgent.exe stream [--fps] [--max-long-edge] [--quality]runs the frame stream used bytransversals stream.tests/: host tests, including a fake guest agentscripts/:build-pkg.shdocs/plans/: design plans
License
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables Windows-native developer orchestration for Claude Code and Codex with PowerShell discovery, capability routing, safety-gated execution, package management, and sandbox-based isolation.MIT
- AlicenseNot gradedqualityFmaintenanceEnables Claude Code to control a Windows desktop via screenshots, mouse, keyboard, and window/display enumeration, reusing the native binding from the Claude desktop app.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP-capable AI assistants to control a Windows computer through GUI automation, file and process operations, PowerShell commands, durable background jobs, and binary file transfer with downloadable exports.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to see and control a Windows desktop through screenshots, built-in OCR, mouse and keyboard input, and accessibility trees read via UI Automation, MSAA and Chrome DevTools Protocol. It also manages windows, virtual desktops and element-level actions such as invoking controls or setting values, running on Node.js with the PowerShell that ships with Windows.9Apache 2.0