3. Common Setup Problems

Common Setup Problems

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

• Symptoms

  • Unity MCP 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 Unity MCP (Claude Code), click "Choose Claude Location" and select the working claude binary, then Register again.

• More details

  • See: Troubleshooting Unity MCP and Claude Code

---

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 Unity MCP 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, run:

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 Unity MCP 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 the 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.

• Notes

  • 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.

---

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 Unity MCP 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. Our 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 Unity MCP window for step-by-step install instructions, then choose the binary location.

FAQ (VSCode)

• Q: When I first set up and start the Unity MCP server in VSCode, I get a failed response that says Canceled: Canceled [see image below]
  • A: Start a new chat, the bad chat didn't 'take' the MCP server configuration.