# Unity MCP Bridge

> Install, configure, and verify CoderGamester/mcp-unity for Unity Editor projects so AI clients can control and query Unity through MCP. Use when asked to add MCP Unity to a Unity project, connect Claude/Cursor/Windsurf/Codex/GitHub Copilot to Unity, start or troubleshoot the Unity MCP bridge, verify get_scene_info/get_console_logs, or generate MCP client configuration for Unity.

- Skill: `kaojunn/unity-mcp-bridge` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kaojunn/unity-mcp-bridge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaojunn/unity-mcp-bridge/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kaojunn (https://skillmd.com/u/kaojunn)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kaojunn/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:

```json
"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:
   ```bash
   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:

```json
{
  "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.