Using Vizspect from a Mac (Parallels)

This is an advanced, optional setup. Most people run Vizspect and their AI assistant on the same Windows machine, and nothing on this page applies to them. See Install & setup and Connecting your AI assistant instead.

This page is for the Mac user who keeps Visio in a Parallels Windows VM and wants their assistant, running on the Mac, to reach it. It works, but unlike the Windows-native setup it needs one command in the Mac Terminal, and the only Mac assistant it supports is Claude Code (the command-line assistant). Other Mac assistants aren’t practical across the VM boundary.

How it fits together

Vizspect runs inside the Windows VM, alongside Visio, exactly as it does on a plain Windows machine. The only difference is that the Mac reaches it over the Parallels network instead of over the local machine. Two things have to be true for that to work, and Vizspect ties them together for you:

  • The server has to accept connections from the Mac (not just from inside the VM). That’s the Allow LAN connections setting, under Advanced → Remote access (Mac / Parallels).
  • Because the server is now reachable beyond the VM, it requires a sign-in token so only your Mac can read or change your drawing. Turning on Allow LAN turns the token on automatically. See App settings.

What you need

  • A Mac with Parallels Desktop, running a Windows VM with Microsoft Visio installed.
  • Vizspect installed and running in the VM (Install & setup).
  • Claude Code installed on the Mac.

Step 1: In the VM, turn on network access

Right-click the Vizspect tray icon and open Advanced. Everything network- related lives in the Remote access (Mac / Parallels) submenu, except the connection URL, which is directly under Advanced:

  1. In Remote access (Mac / Parallels), turn on Allow LAN connections. This lets the Mac reach the server, and automatically turns on Require sign-in token so the connection is never left open. The server restarts (a second or two).
  2. Back under Advanced, click Copy connection URL. With LAN on, this is the VM’s network address, e.g. http://10.211.55.3:8765/mcp. Parallels shares the clipboard with the Mac, so it’s ready to paste there.
  3. In Remote access (Mac / Parallels) again, click Copy sign-in token. This is the secret your Mac assistant must present. Paste it somewhere on the Mac for the next step (again, the shared clipboard carries it across).

If Windows Firewall blocks the connection later, allow inbound TCP port 8765 in the VM. Most Parallels network setups don’t need this.

Step 2: On the Mac, connect Claude Code

Open the Mac Terminal and run this once, substituting the URL and token you copied:

claude mcp add --scope user --transport http visio \
  "http://<VM_IP>:8765/mcp" \
  --header "Authorization: Bearer <token>"

--scope user registers Vizspect for every Claude Code session on the Mac, including ones you start from a matter folder, not just the folder you ran the command in. The Authorization: Bearer header is how Claude Code presents the sign-in token on every request.

Step 3: Verify

In the Terminal:

claude mcp list

You should see visio with a ✔ Connected. Then start a Claude Code session, open Visio in the VM with a drawing, and ask it to draw something, or run /mcp in the session and look for visio: ✓ Connected.

Keeping it connected

  • This is a one-time setup. The token stays the same across restarts, so once it’s registered Claude Code reconnects on its own each session.
  • If the VM’s IP address changes, the connection breaks, because the address is baked into what you registered. This happens when the VM gets a new address from the network (a reboot, a network change). Re-copy Advanced → Copy connection URL in the VM and re-run the Step 2 command with the new URL. If it changes often, giving the VM a fixed address in Parallels’ network settings avoids the churn.
  • If you’d rather not use the token, you can turn off Require sign-in token in the VM and register with just the URL (no --header). Only do this if the Parallels network is one you fully trust. With the token off, anything on that network can reach your open drawing. See App settings for the trade-off.

For general connection problems, see Troubleshooting.