Skip to main content

Common Setup Problems

macOS: Claude CLI fails to start (dyld ICU library not loaded)​

Symptoms:

  • MCP for Unity error: "Failed to start Claude CLI. dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.71.dylib …"
  • Running claude in Terminal fails with missing libicui18n.xx.dylib.

Cause: Homebrew Node (or the claude binary) was linked against an ICU version that's no longer installed; dyld can't find that dylib.

Fix options (pick one):

Reinstall Homebrew Node (relinks to current ICU), then reinstall CLI:

brew update
brew reinstall node
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

Use NVM Node (avoids Homebrew ICU churn):

nvm install --lts
nvm use --lts
npm install -g @anthropic-ai/claude-code
# Unity MCP → Claude Code → Choose Claude Location → ~/.nvm/versions/node/<ver>/bin/claude

Use the native installer (puts claude in a stable path):

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# Unity MCP → Claude Code → Choose Claude Location → /opt/homebrew/bin/claude or ~/.local/bin/claude

After fixing: in MCP for Unity (Claude Code section), click "Choose Claude Location" and select the working claude binary, then Register again.

WSL2: Connecting Claude Code (Linux) to Unity (Windows)​

If you're running Claude Code from WSL2 and Unity on Windows, the MCP server runs on the Windows side but Claude Code needs to reach it from WSL. Here's how to bridge the two.

Contributed by @aollivier82.

1. Install the Unity package​

In Unity Package Manager, add by git URL:

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

In the MCP for Unity settings, change the port to 8090 (or any free port — the default 8080 can conflict with other services like Tailscale).

2. Install uv on Windows​

The MCP server requires uv. From an admin PowerShell:

irm https://astral.sh/uv/install.ps1 | iex

3. Set up port forwarding from WSL to Windows​

WSL2 runs in a separate network namespace, so you need to forward the MCP port. From an admin PowerShell:

netsh interface portproxy add v4tov4 listenport=8090 listenaddress=0.0.0.0 connectport=8090 connectaddress=127.0.0.1

Then add a firewall rule to allow it:

New-NetFirewallRule -DisplayName "Unity MCP Server" -Direction Inbound -LocalPort 8090 -Protocol TCP -Action Allow

4. Find your WSL host IP​

From inside WSL:

cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

This prints the Windows host IP as seen from WSL (e.g. 172.21.48.1). It's a private address that varies per machine.

5. Add the MCP server to Claude Code​

From WSL, using the IP from step 4:

claude mcp add --transport http UnityMCP http://<YOUR_WSL_HOST_IP>:8090/mcp

For example:

claude mcp add --transport http UnityMCP http://172.21.48.1:8090/mcp

Note: this uses HTTP transport, not stdio — since the server is running on the Windows side.

6. Verify​

Start Unity, then start Claude Code. You should see UnityMCP listed as a connected MCP server. Test it by asking Claude to get your scene info.

Notes:

  • If you restart your machine, the WSL host IP may change. Re-run step 4 and update the MCP config if needed.
  • The port proxy persists across reboots. To remove it later: netsh interface portproxy delete v4tov4 listenport=8090 listenaddress=0.0.0.0
  • If the connection fails, make sure Unity is running and the MCP server is started (check the MCP for Unity panel).

DLL reference mismatch with Unity AI Assistant package​

If you're using Unity 6.3+ alongside the Unity AI Assistant package, you may encounter System.Collections.Immutable version conflicts.

Reported by @rkroska.

Symptoms:

  • Compilation errors referencing System.Collections.Immutable version mismatches
  • Errors appear after installing MCP for Unity in a project that has the Unity AI Assistant package

Cause: Unity AI Assistant bundles System.Collections.Immutable v10, while MCP for Unity's CodeAnalysis dependency needs v9. Unity's built-in version may be v8. These conflict during assembly resolution.

Fix options:

  • Option A (recommended): If you don't need Unity AI Assistant, remove it via Package Manager. Then install System.Collections.Immutable v9.0.0 as a DLL in Assets/Plugins/.
  • Option B: If you need both packages, install System.Collections.Immutable v9.0.0 in Assets/Plugins/ to satisfy MCP's dependency. The AI Assistant's v10 reference should be forward-compatible.

Note: This is a Unity assembly resolution issue, not specific to MCP for Unity. Unity doesn't have a NuGet-style dependency resolver, so DLL version conflicts must be resolved manually.

"No Unity Instances Found"​

When in doubt, restart your client

Clients like Claude Code or JetBrains Rider can get confused if you switch transport modes mid-session. Restart the client so it picks up the new configuration.

If restarting doesn't fix it:

  • Check the MCP for Unity status panel — does it say Connected?
  • Open mcpforunity://instances in your client. If it returns an empty list, the Unity-side bridge isn't running.
  • Try Window → MCP for Unity → Restart Server.

FAQ — Claude Code​

Q: Unity can't find claude even though Terminal can. A: macOS apps launched from Finder / Hub don't inherit your shell PATH. In the MCP for Unity window, click "Choose Claude Location" and select the absolute path (e.g., /opt/homebrew/bin/claude or ~/.nvm/versions/node/<ver>/bin/claude).

Q: I installed via NVM; where is claude? A: Typically ~/.nvm/versions/node/<ver>/bin/claude. The MCP for Unity UI also scans NVM versions and you can browse to it via "Choose Claude Location".

Q: The Register button says "Claude Not Found". A: Install the CLI or set the path. Click the orange [HELP] link in the MCP for Unity window for step-by-step install instructions, then choose the binary location. See also: Install or Repair Claude Code CLI.

FAQ — VS Code​

Q: When I first set up and start the MCP for Unity server in VS Code, I get a failed response that says Canceled: Canceled. A: Start a new chat — the bad chat didn't pick up the MCP server configuration.

Canceled error screenshot

FAQ — Cursor / Windsurf / VS Code (Windows uv path)​

Q: My MCP client keeps failing to launch the server even though uv is installed. A: Some Windows machines have multiple uv.exe locations. Auto-config sometimes picks a less stable path, causing the launch to fail or auto-rewrite on every restart. Use "Choose UV Install Location" in the MCP for Unity window and pin the WinGet Links shim path (%LOCALAPPDATA%\Microsoft\WinGet\Links\uv.exe) — it's stable across uv upgrades.