From 4553641a390a365eca6df70836edcbdf18ee34d8 Mon Sep 17 00:00:00 2001 From: David Sarno Date: Wed, 3 Sep 2025 18:13:19 -0700 Subject: [PATCH 1/6] fix: Update README installation paths to match ServerInstaller.cs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Windows: Fix path from AppData\Local\Programs\UnityMCP to AppData\Local\UnityMCP - macOS: Update from /usr/local/bin/UnityMCP to Library/AppSupport/UnityMCP (uses symlink) - Linux: Change from /home/USERNAME/bin/UnityMCP to .local/share/UnityMCP - Update Claude Code command examples with correct paths 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 41bec68ea..627a370e3 100644 --- a/README.md +++ b/README.md @@ -181,7 +181,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L "args": [ "run", "--directory", - "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src", + "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\UnityMCP\\UnityMcpServer\\src", "server.py" ] } @@ -202,7 +202,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L "args": [ "run", "--directory", - "/usr/local/bin/UnityMCP/UnityMcpServer/src", + "/Users/YOUR_USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src", "server.py" ] } @@ -211,7 +211,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L } ``` -(Replace YOUR_USERNAME if using ~/bin) +(Replace YOUR_USERNAME. Note: AppSupport is a symlink to "Application Support" to avoid quoting issues) **Linux:** @@ -223,7 +223,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L "args": [ "run", "--directory", - "/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src", + "/home/YOUR_USERNAME/.local/share/UnityMCP/UnityMcpServer/src", "server.py" ] } @@ -241,13 +241,13 @@ If you\'re using Claude Code, you can register the MCP server using these comman **macOS:** ```bash -claude mcp add UnityMCP -- uv --directory /[PATH_TO]/UnityMCP/UnityMcpServer/src run server.py +claude mcp add UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src run server.py ``` **Windows:** ```bash -claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/Scripts/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/Programs/UnityMCP/UnityMcpServer/src" run server.py +claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/Scripts/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py ``` From 8d0539b039ea81424d5800e499ec759b6952e29f Mon Sep 17 00:00:00 2001 From: David Sarno Date: Fri, 5 Sep 2025 08:32:00 -0700 Subject: [PATCH 2/6] docs: update README.md with improved installation paths, documentation, and logo --- README.md | 104 ++++++++++++++++-------------------------------------- 1 file changed, 30 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 627a370e3..e6fd131dd 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# MCP for Unity ✨ +MCP for Unity #### Proudly sponsored and maintained by [Coplay](https://www.coplay.dev/?ref=unity-mcp) -- the best AI assistant for Unity. [Read the backstory here.](https://www.coplay.dev/blog/coplay-and-open-source-unity-mcp-join-forces) @@ -15,9 +15,9 @@ MCP for Unity acts as a bridge, allowing AI assistants (like Claude, Cursor) to interact directly with your Unity Editor via a local **MCP (Model Context Protocol) Client**. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity. -## 💬 Join Our Community +--- -### [Discord](https://discord.gg/y4p8KfzrN4) +### 💬 Join Our [Discord](https://discord.gg/y4p8KfzrN4) **Get help, share ideas, and collaborate with other MCP for Unity developers!** @@ -37,7 +37,7 @@ MCP for Unity acts as a bridge, allowing AI assistants (like Claude, Cursor) to * `read_console`: Gets messages from or clears the console. * `manage_script`: Manages C# scripts (create, read, update, delete). - * `manage_editor`: Controls and queries the editor\'s state and settings. + * `manage_editor`: Controls and queries the editor's state and settings. * `manage_scene`: Manages scenes (load, save, create, get hierarchy, etc.). * `manage_asset`: Performs asset operations (import, create, modify, delete, etc.). * `manage_shader`: Performs shader CRUD operations (create, read, modify, delete). @@ -50,21 +50,19 @@ MCP for Unity acts as a bridge, allowing AI assistants (like Claude, Cursor) to --- -## How It Works 🤔 +## How It Works MCP for Unity connects your tools using two components: 1. **MCP for Unity Bridge:** A Unity package running inside the Editor. (Installed via Package Manager). 2. **MCP for Unity Server:** A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed automatically by the package on first run or via Auto-Setup; manual setup is available as a fallback). -**Flow:** `[Your LLM via MCP Client] <-> [MCP for Unity Server (Python)] <-> [MCP for Unity Bridge (Unity Editor)]` +image --- ## Installation ⚙️ -> **Note:** The setup is constantly improving as we update the package. Check back if you randomly start to run into issues. - ### Prerequisites * **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/) @@ -74,13 +72,8 @@ MCP for Unity connects your tools using two components: pip install uv # Or see: https://docs.astral.sh/uv/getting-started/installation/ ``` - * **An MCP Client:** - * [Claude Desktop](https://claude.ai/download) - * [Claude Code](https://github.com/anthropics/claude-code) - * [Cursor](https://www.cursor.com/en/downloads) - * [Visual Studio Code Copilot](https://code.visualstudio.com/docs/copilot/overview) - * [Windsurf](https://windsurf.com) - * *(Others may work with manual config)* + * **An MCP Client:** : [Claude Desktop](https://claude.ai/download) | [Claude Code](https://github.com/anthropics/claude-code) | [Cursor](https://www.cursor.com/en/downloads) | [Visual Studio Code Copilot](https://code.visualstudio.com/docs/copilot/overview) | [Windsurf](https://windsurf.com) | Others work with manual config + *
[Optional] Roslyn for Advanced Script Validation For **Strict** validation level that catches undefined namespaces, types, and methods: @@ -102,7 +95,8 @@ MCP for Unity connects your tools using two components: **Note:** Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.
-### 🌟Step 1: Install the Unity Package🌟 +--- +### 🌟Install the Unity Package🌟 #### To install via Git URL @@ -118,7 +112,7 @@ MCP for Unity connects your tools using two components: #### To install via OpenUPM -1. Instal the [OpenUPM CLI](https://openupm.com/docs/getting-started-cli.html) +1. Install the [OpenUPM CLI](https://openupm.com/docs/getting-started-cli.html) 2. Open a terminal (PowerShell, Terminal, etc.) and navigate to your Unity project directory 3. Run `openupm add com.coplaydev.unity-mcp` @@ -134,7 +128,7 @@ Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in St 1. In Unity, go to `Window > MCP for Unity`. 2. Click `Auto-Setup`. -3. Look for a green status indicator 🟢 and "Connected ✓". *(This attempts to modify the MCP Client\'s config file automatically).* +3. Look for a green status indicator 🟢 and "Connected ✓". *(This attempts to modify the MCP Client's config file automatically).*
Client-specific troubleshooting @@ -147,7 +141,7 @@ Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in St If Auto-Setup fails or you use a different client: -1. **Find your MCP Client\'s configuration file.** (Check client documentation). +1. **Find your MCP Client's configuration file.** (Check client documentation). * *Claude Example (macOS):* `~/Library/Application Support/Claude/claude_desktop_config.json` * *Claude Example (Windows):* `%APPDATA%\Claude\claude_desktop_config.json` 2. **Edit the file** to add/update the `mcpServers` section, using the *exact* paths from Step 1. @@ -236,7 +230,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L **For Claude Code** -If you\'re using Claude Code, you can register the MCP server using these commands: +If you're using Claude Code, you can register the MCP server using these commands: **macOS:** @@ -261,58 +255,19 @@ claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/S 3. **Interact!** Unity tools should now be available in your MCP Client. - Example Prompt: `Create a 3D player controller`, `Create a yellow and bridge sun`, `Create a cool shader and apply it on a cube`. + Example Prompt: `Create a 3D player controller`, `Create a tic-tac-toe game in 3D`, `Create a cool shader and apply to a cube`. --- -## Future Dev Plans (Besides PR) 📝 - -### 🔴 High Priority - -- [ ] **Asset Generation Improvements** - Enhanced server request handling and asset pipeline optimization -- [ ] **Code Generation Enhancements** - Improved generated code quality and error handling -- [ ] **Robust Error Handling** - Comprehensive error messages, recovery mechanisms, and graceful degradation -- [ ] **Remote Connection Support** - Enable seamless remote connection between Unity host and MCP server -- [ ] **Documentation Expansion** - Complete tutorials for custom tool creation and API reference - -### 🟡 Medium Priority - -- [ ] **Custom Tool Creation GUI** - Visual interface for users to create and configure their own MCP tools -- [ ] **Advanced Logging System** - Logging with filtering, export, and debugging capabilities - -### 🟢 Low Priority - -- [ ] **Mobile Platform Support** - Extended toolset for mobile development workflows and platform-specific features -- [ ] **Easier Tool Setup** -- [ ] **Plugin Marketplace** - Community-driven tool sharing and distribution platform - -
- ✅ Completed Features - - - [x] **Shader Generation** - Generate shaders using CGProgram template - - [x] **Advanced Script Validation** - Multi-level validation with semantic analysis, namespace/type checking, and Unity best practices (Will need Roslyn Installed, see [Prerequisite](#prerequisites)). -
+## Development & Contributing 🛠️ -### 🔬 Research & Exploration +### For Developers -- [ ] **AI-Powered Asset Generation** - Integration with AI tools for automatic 3D models, textures, and animations -- [ ] **Real-time Collaboration** - Live editing sessions between multiple developers *(Currently in progress)* -- [ ] **Analytics Dashboard** - Usage analytics, project insights, and performance metrics -- [ ] **Voice Commands** - Voice-controlled Unity operations for accessibility -- [ ] **AR/VR Tool Integration** - Extended support for immersive development workflows - ---- - -## For Developers 🛠️ - -### Development Tools - -If you\'re contributing to MCP for Unity or want to test core changes, we have development tools to streamline your workflow: +If you're contributing to MCP for Unity or want to test core changes, we have development tools to streamline your workflow: - **Development Deployment Scripts**: Quickly deploy and test your changes to MCP for Unity Bridge and Python Server - **Automatic Backup System**: Safe testing with easy rollback capabilities - **Hot Reload Workflow**: Fast iteration cycle for core development -- **More coming!** 📖 **See [README-DEV.md](README-DEV.md)** for complete development setup and workflow documentation. @@ -321,15 +276,10 @@ If you\'re contributing to MCP for Unity or want to test core changes, we have d Help make MCP for Unity better! 1. **Fork** the main repository. - 2. **Create a branch** (`feature/your-idea` or `bugfix/your-fix`). - 3. **Make changes.** - 4. **Commit** (feat: Add cool new feature). - 5. **Push** your branch. - 6. **Open a Pull Request** against the main branch. --- @@ -344,12 +294,18 @@ Help make MCP for Unity better! - Check the status window: Window > MCP for Unity. - Restart Unity. - **MCP Client Not Connecting / Server Not Starting:** - - **Verify Server Path:** Double-check the --directory path in your MCP Client\'s JSON config. It must exactly match the location where you cloned the UnityMCP repository in Installation Step 1 (e.g., .../Programs/UnityMCP/UnityMcpServer/src). - - **Verify uv:** Make sure `uv` is installed and working (pip show uv). - - **Run Manually:** Try running the server directly from the terminal to see errors: `# Navigate to the src directory first! cd /path/to/your/UnityMCP/UnityMcpServer/src uv run server.py` - - **Permissions (macOS/Linux):** If you installed the server in a system location like /usr/local/bin, ensure the user running the MCP client has permission to execute uv and access files there. Installing in ~/bin might be easier. + - **Verify Server Path:** Double-check the --directory path in your MCP Client's JSON config. It must exactly match the installation location: + - **Windows:** `%USERPROFILE%\AppData\Local\UnityMCP\UnityMcpServer\src` + - **macOS:** `~/Library/AppSupport/UnityMCP/UnityMcpServer\src` + - **Linux:** `~/.local/share/UnityMCP/UnityMcpServer\src` + - **Verify uv:** Make sure `uv` is installed and working (`uv --version`). + - **Run Manually:** Try running the server directly from the terminal to see errors: + ```bash + cd /path/to/your/UnityMCP/UnityMcpServer/src + uv run server.py + ``` - **Auto-Configure Failed:** - - Use the Manual Configuration steps. Auto-configure might lack permissions to write to the MCP client\'s config file. + - Use the Manual Configuration steps. Auto-configure might lack permissions to write to the MCP client's config file.
@@ -373,4 +329,4 @@ MIT License. See [LICENSE](LICENSE) file. Coplay Logo -

+

\ No newline at end of file From 574d1044257cd7f074e21be0c2b8e3702e49d9f6 Mon Sep 17 00:00:00 2001 From: David Sarno Date: Fri, 5 Sep 2025 08:48:50 -0700 Subject: [PATCH 3/6] docs: fix Windows uv path to use WinGet shim, keep macOS AppSupport symlink path --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e6fd131dd..bc991e7a8 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ MCP for Unity connects your tools using two components: **Note:** Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting. --- -### 🌟Install the Unity Package🌟 +### Step 1: 🌟Install the Unity Package🌟 #### To install via Git URL @@ -118,8 +118,8 @@ MCP for Unity connects your tools using two components: **Note:** If you installed the MCP Server before Coplay's maintenance, you will need to uninstall the old package before re-installing the new one. -### Step 2: Configure Your MCP Client - +### 🛠️ Step 2: Configure Your MCP Client 🛠️ +e w Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below). MCPForUnity-Readme-Image @@ -241,7 +241,7 @@ claude mcp add UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/Uni **Windows:** ```bash -claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/Scripts/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py +claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py ``` @@ -329,4 +329,4 @@ MIT License. See [LICENSE](LICENSE) file. Coplay Logo -

\ No newline at end of file +

From 963b5e1afd6d48c038101cfd35469e6f30371cfb Mon Sep 17 00:00:00 2001 From: dsarno Date: Fri, 5 Sep 2025 08:55:17 -0700 Subject: [PATCH 4/6] Update README.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index bc991e7a8..4cc219db2 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,6 @@ MCP for Unity connects your tools using two components: **Note:** If you installed the MCP Server before Coplay's maintenance, you will need to uninstall the old package before re-installing the new one. ### 🛠️ Step 2: Configure Your MCP Client 🛠️ -e w Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below). MCPForUnity-Readme-Image From 94fcff4c909e2bc5b11f6567a14d1e8459a639d8 Mon Sep 17 00:00:00 2001 From: David Sarno Date: Fri, 5 Sep 2025 09:15:54 -0700 Subject: [PATCH 5/6] docs: install uv via official installer (curl/winget) --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4cc219db2..256c7d8fd 100644 --- a/README.md +++ b/README.md @@ -67,11 +67,17 @@ MCP for Unity connects your tools using two components: * **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/) * **Unity Hub & Editor:** Version 2021.3 LTS or newer. [Download Unity](https://unity.com/download) - * **uv (Python package manager):** + * **uv (Python toolchain manager):** ```bash - pip install uv - # Or see: https://docs.astral.sh/uv/getting-started/installation/ + # macOS / Linux + curl -LsSf https://astral.sh/uv/install.sh | sh + + # Windows (PowerShell) + winget install Astral.Sh.Uv + + # Docs: https://docs.astral.sh/uv/getting-started/installation/ ``` + * **An MCP Client:** : [Claude Desktop](https://claude.ai/download) | [Claude Code](https://github.com/anthropics/claude-code) | [Cursor](https://www.cursor.com/en/downloads) | [Visual Studio Code Copilot](https://code.visualstudio.com/docs/copilot/overview) | [Windsurf](https://windsurf.com) | Others work with manual config *
[Optional] Roslyn for Advanced Script Validation From 2d3ec51a2b6241d4051531221d36b1eda0b74021 Mon Sep 17 00:00:00 2001 From: dsarno Date: Fri, 5 Sep 2025 11:08:58 -0700 Subject: [PATCH 6/6] Revise README for improved clarity and organization Updated section headings for clarity and consistency. Removed redundant instructions for Claude Code registration. --- README.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 256c7d8fd..cdd93fbc5 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ MCP for Unity connects your tools using two components: **Note:** Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.
--- -### Step 1: 🌟Install the Unity Package🌟 +### 🌟 Step 1: Install the Unity Package #### To install via Git URL @@ -124,7 +124,7 @@ MCP for Unity connects your tools using two components: **Note:** If you installed the MCP Server before Coplay's maintenance, you will need to uninstall the old package before re-installing the new one. -### 🛠️ Step 2: Configure Your MCP Client 🛠️ +### 🛠️ Step 2: Configure Your MCP Client Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below). MCPForUnity-Readme-Image @@ -154,6 +154,23 @@ If Auto-Setup fails or you use a different client:
Click for Client-Specific JSON Configuration Snippets... + --- +**Claude Code** + +If you're using Claude Code, you can register the MCP server using the below commands: +🚨**make sure to run these from your Unity project's home directory**🚨 + +**macOS:** + +```bash +claude mcp add UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src run server.py +``` + +**Windows:** + +```bash +claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py +``` **VSCode (all OS)** ```json @@ -233,21 +250,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L (Replace YOUR_USERNAME) -**For Claude Code** -If you're using Claude Code, you can register the MCP server using these commands: - -**macOS:** - -```bash -claude mcp add UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src run server.py -``` - -**Windows:** - -```bash -claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py -```
---