History

Marcus Sanatan 7f44e4b53e Add CLI (#606 ) * feat: Add CLI for Unity MCP server - Add click-based CLI with 15+ command groups - Commands: gameobject, component, scene, asset, script, editor, prefab, material, lighting, ui, audio, animation, code - HTTP transport to communicate with Unity via MCP server - Output formats: text, json, table - Configuration via environment variables or CLI options - Comprehensive usage guide and unit tests * Update based on AI feedback * Fixes main.py error * Update for further error fix * Update based on AI * Update script.py * Update with better coverage and Tool Readme * Log a message with implicit URI changes Small update for #542 * Minor fixes (#602) * Log a message with implicit URI changes Small update for #542 * Log a message with implicit URI changes Small update for #542 * Add helper scripts to update forks * fix: improve HTTP Local URL validation UX and styling specificity - Rename CSS class from generic "error" to "http-local-url-error" for better specificity - Rename "invalid-url" class to "http-local-invalid-url" for clarity - Disable httpServerCommandField when URL is invalid or transport not HTTP Local - Clear field value and tooltip when showing validation errors - Ensure field is re-enabled when URL becomes valid * Docker mcp gateway (#603) * Log a message with implicit URI changes Small update for #542 * Update docker container to default to stdio Replaces #541 * fix: Rider config path and add MCP registry manifest (#604) - Fix RiderConfigurator to use correct GitHub Copilot config path: - Windows: %LOCALAPPDATA%\github-copilot\intellij\mcp.json - macOS: ~/Library/Application Support/github-copilot/intellij/mcp.json - Linux: ~/.config/github-copilot/intellij/mcp.json - Add mcp.json for GitHub MCP Registry support: - Enables users to install via coplaydev/unity-mcp - Uses uvx with mcpforunityserver from PyPI * Use click.echo instead of print statements * Standardize whitespace * Minor tweak in docs * Use `wait` params * Unrelated but project scoped tools should be off by default * Update lock file * Whitespace cleanup * Update custom_tool_service.py to skip global registration for any tool name that already exists as a built‑in. * Avoid silently falling back to the first Unity session when a specific unity_instance was requested but not found. If a client passes a unity_instance that doesn’t match any session, this code will still route the command to the first available session, which can send commands to the wrong project in multi‑instance environments. Instead, when a unity_instance is provided but no matching session_id is found, return an error (e.g. 400/404 with "Unity instance '' not found") and only default to the first session when no unity_instance was specified. Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Update docs/CLI_USAGE.md Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Updated the CLI command registration to only swallow missing optional modules and to surface real import-time failures, so broken command modules don’t get silently ignored. * Sorted __all__ alphabetically to satisfy RUF022 in __init__.py. * Validate --params is a JSON object before merging. Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --------- Co-authored-by: Shutong Wu <51266340+Scriptwonder@users.noreply.github.com> Co-authored-by: dsarno <david@lighthaus.us> Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>		2026-01-21 20:53:13 -04:00
..
Editor	Add CLI (#606 )	2026-01-21 20:53:13 -04:00
Runtime	Replace asmdef GUID references (#564 )	2026-01-15 07:52:53 -08:00
Editor.meta	Rename plugin folder to MCPForUnity (#303 )	2025-10-03 20:23:28 -04:00
README.md	HTTP Server, uvx, C# only custom tools (#375 )	2025-11-24 23:21:06 -04:00
README.md.meta	Rename plugin folder to MCPForUnity (#303 )	2025-10-03 20:23:28 -04:00
Runtime.meta	Rename plugin folder to MCPForUnity (#303 )	2025-10-03 20:23:28 -04:00
package.json	chore: bump version to 9.0.8	2026-01-19 14:07:05 +00:00
package.json.meta	Add .meta files (#472 )	2025-12-19 18:59:19 -04:00

README.md

MCP for Unity — Editor Plugin Guide

Use this guide to configure and run MCP for Unity inside the Unity Editor. Installation is covered elsewhere; this document focuses on the Editor window, client configuration, and troubleshooting.

Open the window

Unity menu: Window > MCP for Unity

The window has four areas: Server Status, Unity Bridge, MCP Client Configuration, and Script Validation.

Quick start

Open Window > MCP for Unity.
Click “Auto-Setup”.
If prompted:
- Select the packaged server folder (Server) if you want to run the bundled implementation.
- Install Python and/or uv/uvx if missing so the server can be managed locally.
- For Claude Code, ensure the claude CLI is installed.
Click “Start Bridge” if the Unity Bridge shows “Stopped”.
Use your MCP client (Cursor, VS Code, Windsurf, Claude Code) to connect.

Server Status

Status dot and label:
- Installed / Installed (Embedded) / Not Installed.
Mode and ports:
- Mode: Auto or Standard.
- Ports: Unity (varies; shown in UI), MCP 6500.
Actions:
- Auto-Setup: Registers/updates your selected MCP client(s), ensures bridge connectivity. Shows “Connected ✓” after success.
- Rebuild MCP Server: Rebuilds the Python based MCP server
- Select server folder…: Choose the folder containing server.py.
- Verify again: Re-checks server presence.
- If Python isn’t detected, use “Open Install Instructions”.
HTTP Server Command foldout:
- Expands to display the exact uvx command Unity will run.
- Includes a copy button and the “Start Local HTTP Server” action so you can launch or reuse the command elsewhere.

Unity Bridge

Shows Running or Stopped with a status dot.
Start/Stop Bridge button toggles the Unity bridge process used by MCP clients to talk to Unity.
Tip: After Auto-Setup, the bridge may auto-start in Auto mode.

MCP Client Configuration

Select Client: Choose your target MCP client (e.g., Cursor, VS Code, Windsurf, Claude Code).
Per-client actions:
- Cursor / VS Code / Windsurf:
  - Auto Configure: Writes/updates your config to launch the server via uvx with the current package version:
    - Command: uvx (or your overridden path)
    - Args: --from mcp-for-unity
  - Manual Setup: Opens a window with a pre-filled JSON snippet to copy/paste into your client config.
  - Choose UV Install Location: If uv/uvx isn’t on PATH, select the executable.
  - A compact “Config:” line shows the resolved config file name once uv/server are detected.
- Claude Code:
  - Register with Claude Code / Unregister MCP for Unity with Claude Code.
  - If the CLI isn’t found, click “Choose Claude Install Location”.
  - The window displays the resolved Claude CLI path when detected.

Notes:

The UI shows a status dot and a short status text (e.g., “Configured”, “uv Not Found”, “Claude Not Found”).
Use “Auto Configure” for one-click setup; use “Manual Setup” when you prefer to review/copy config.

Script Validation

Validation Level options:
- Basic — Only syntax checks
- Standard — Syntax + Unity practices
- Comprehensive — All checks + semantic analysis
- Strict — Full semantic validation (requires Roslyn)
Pick a level based on your project’s needs. A description is shown under the dropdown.

Troubleshooting

Python or uv not found:
- Help: Fix MCP for Unity with Cursor, VS Code & Windsurf
Claude CLI not found:
- Help: Fix MCP for Unity with Claude Code

Tips

Use Cmd+Shift+M (macOS) / Ctrl+Shift+M (Windows, Linux) to toggle the MCP for Unity window.
Enable “Show Debug Logs” in the header for more details in the Console when diagnosing issues.

README.md Unescape Escape