Unity MCP Bridge

Unity MCP Bridge

Overview

Use this skill to connect an AI client to the currently open or specified Unity project through CoderGamester/mcp-unity.

Default install mode: add the Unity Package Manager Git dependency:

"com.gamelovers.mcp-unity": "https://github.com/CoderGamester/mcp-unity.git"

Do not use the embedded package fallback unless the user explicitly asks or Git/Package Manager resolution fails.

Quick Workflow

1. Identify the Unity project path.
   • Prefer a user-provided project path.
   • Otherwise run scripts/install_mcp_unity.py from the likely project root or a parent directory; it searches for ProjectSettings/ProjectVersion.txt and Packages/manifest.json.
   • If multiple candidate projects are found, ask the user which one to modify.
2. Install the package dependency:

   python3 /Users/a111/.codex/skills/unity-mcp-bridge/scripts/install_mcp_unity.py /absolute/path/to/UnityProject
   

3. Return to Unity and wait for Package Manager/script compilation.
4. Open Tools -> MCP Unity -> Server Window.
5. Click Start Server.
6. If the Node server is not built, click Force Install Server, then Start Server again.
7. Verify the bridge from the AI host:
   • Call get_scene_info.
   • Call get_console_logs with includeStackTrace: false.
   • Success means the AI receives active scene info and Unity Console logs show a WebSocket client connected.

Client Configuration

For client-specific MCP configuration examples, read references/client-configs.md.

Use Unity's Tools -> MCP Unity -> Server Window -> Configure when available. Prefer manual config only when automatic configuration is unavailable or the user wants a specific client file edited.

Manual config shape:

{
  "mcpServers": {
    "mcp-unity": {
      "command": "node",
      "args": [
        "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
      ]
    }
  }
}

The server path usually resolves to one of:

• Git package cache: Library/PackageCache/com.gamelovers.mcp-unity@.../Server~/build/index.js
• Embedded package: Packages/com.gamelovers.mcp-unity/Server~/build/index.js

Troubleshooting

• Package does not appear in Unity: verify Packages/manifest.json, reopen Package Manager, and check Unity Console for Git/Package Manager errors.
• MCP calls time out: open Tools -> MCP Unity -> Server Window, confirm the WebSocket server is started, and confirm Node server build exists.
• Server path missing build/index.js: click Force Install Server in the Unity MCP server window.
• Port mismatch: default Unity WebSocket is localhost:8090; if changed, restart the Node MCP server and ensure the AI host uses the same Unity port environment.
• Play Mode disconnects: this is usually domain reload. Disable Reload Domain under Unity Editor Enter Play Mode settings when running Play Mode tests through MCP.

Important Defaults

• Do not install Node.js automatically. Report missing Node/npm and give clear next steps.
• Do not edit Claude/Cursor/Windsurf/Codex/GitHub Copilot config unless the user explicitly asks.
• Do not overwrite an existing com.gamelovers.mcp-unity dependency. Report whether it is Git URL, embedded, registry, file, or unknown.
• Prefer non-stacktrace Unity logs for routine verification to avoid noisy output.