megaproxy/jankenbots
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions
jankenbots/docs/mcp-setup.md

4 KiB
Raw Blame History

Unity MCP setup — Claude (WSL) driving the Unity Editor (Windows)

Goal: let Claude Code (running in WSL) control the Unity Editor (running on the Windows host) via MCP — the same pattern our UE projects already use (nwiro / ChiR24): the MCP server runs host-side over HTTP, and Claude in WSL connects across the WSL↔Windows boundary by its host IP.

Server: CoplayDev/unity-mcp ("MCP for Unity", MIT, ~12k★). Chosen because it's the most popular/maintained and — critically — supports an HTTP transport (url: http://host:8080/mcp), which bridges the WSL boundary cleanly instead of a same-machine stdio assumption.

The in-editor "Configure All Detected Clients" button will not find WSL's claude (it looks on Windows), so we configure Claude manually via the committed .mcp.json (already in this repo) pointed at the Windows host IP.

Current values (this machine)

  • Windows host IP as seen from WSL: 172.27.208.1 (the WSL default gateway; confirm with ip route show default). This can change across WSL restarts — if MCP stops connecting, re-check it and update .mcp.json.
  • MCP HTTP port: 8080 (CoplayDev default). If something else on Windows already uses 8080, change it in the Unity panel and in .mcp.json.
  • .mcp.json (committed) → {"unity": {"type":"http","url":"http://172.27.208.1:8080/mcp"}}
  • .claude/settings.local.json (local) pre-enables the unity server.

One-time setup (do on Windows, in the Unity Editor)

  1. Create/open the Unity project at F:\jankenstein (Unity LTS). This repo already lives there — Unity will add Assets/, Packages/, ProjectSettings/ alongside the existing files.
  2. Install the package: Window → Package Manager → + → Add package from git URL… 
    https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
  3. Open Window → MCP for Unity. Switch the transport to HTTP and Start the server (listens on :8080). Note the exact port shown.
  4. Make it reachable from WSL. The HTTP server binds loopback by default, so pick one:
    • (a) If the panel exposes a non-loopback / 0.0.0.0 / "listen on all interfaces" option, enable it. Then WSL reaches it directly at http://172.27.208.1:8080/mcp.
    • (b) Otherwise add a Windows port-proxy + firewall rule (admin PowerShell) — same trick pair-o-dox uses for nwiro: 
      netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8080 connectaddress=127.0.0.1 connectport=8080
New-NetFirewallRule -DisplayName "Unity MCP 8080" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8080
      Remove later with netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080.

Connect from WSL (Claude Code)

  1. Make sure the Unity Editor is running with the project open and the MCP server is Started (step 3 above) — the tools only work while the editor is live.
  2. Run Claude from this folder (/mnt/f/jankenstein, or the symlink ~/claude/projects/jankenstein). The committed .mcp.json + .claude/settings.local.json register/enable the unity server.
  3. Restart the Claude session after any transport or .mcp.json change so it re-reads the config.
  4. Verify: Claude should see mcp__unity__* tools. Quick smoke test: ask it to read the open scene / list GameObjects. If it fails:
    • curl -s http://172.27.208.1:8080/mcp from WSL — no response ⇒ the bridge (step 4) isn't up or the IP changed.
    • Confirm the editor is open and the server Started.
    • Re-check the gateway IP (ip route show default).

Gotchas

  • Editor must be open with the project loaded — MCP drives the live editor, it doesn't launch it.
  • IP drift: the WSL gateway IP (172.27.208.1) can change on WSL restart; update .mcp.json if so.
  • HTTP↔stdio toggling in the Unity panel requires a Claude restart to pick up.
  • This is editor tooling, unrelated to the game's own netcode (NGO + Relay) — different layer entirely.