PHXH
/
unity-mcp
51
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #265 from dsarno/update-readme-docs 

Update * Clean up README, fix install paths, add logo
main
dsarno 2025-09-05 11:10:21 -07:00 committed by GitHub
parent b7411e2cde 2d3ec51a2b
commit 741b4f7671
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 59 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
README.md
View File

@ -1,4 +1,4 @@
# MCP for Unity ✨ <img width="676" height="380" alt="MCP for Unity" src="https://github.com/user-attachments/assets/b712e41d-273c-48b2-9041-82bd17ace267" />
#### 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) #### 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. 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!** **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. * `read_console`: Gets messages from or clears the console.
* `manage_script`: Manages C# scripts (create, read, update, delete). * `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_scene`: Manages scenes (load, save, create, get hierarchy, etc.).
* `manage_asset`: Performs asset operations (import, create, modify, delete, etc.). * `manage_asset`: Performs asset operations (import, create, modify, delete, etc.).
* `manage_shader`: Performs shader CRUD operations (create, read, modify, delete). * `manage_shader`: Performs shader CRUD operations (create, read, modify, delete).
@ -50,37 +50,36 @@ 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: 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). 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). 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)]` <img width="562" height="121" alt="image" src="https://github.com/user-attachments/assets/9abf9c66-70d1-4b82-9587-658e0d45dc3e" />
--- ---
## Installation ⚙️ ## Installation ⚙️
> **Note:** The setup is constantly improving as we update the package. Check back if you randomly start to run into issues.
### Prerequisites ### Prerequisites
* **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/) * **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) * **Unity Hub & Editor:** Version 2021.3 LTS or newer. [Download Unity](https://unity.com/download)
* **uv (Python package manager):** * **uv (Python toolchain manager):**
```bash ```bash
pip install uv # macOS / Linux
# Or see: https://docs.astral.sh/uv/getting-started/installation/ 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) * **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
* [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)*
* <details> <summary><strong>[Optional] Roslyn for Advanced Script Validation</strong></summary> * <details> <summary><strong>[Optional] Roslyn for Advanced Script Validation</strong></summary>
For **Strict** validation level that catches undefined namespaces, types, and methods: For **Strict** validation level that catches undefined namespaces, types, and methods:
@ -102,7 +101,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.</details> **Note:** Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.</details>
### 🌟Step 1: Install the Unity Package🌟 ---
### 🌟 Step 1: Install the Unity Package
#### To install via Git URL #### To install via Git URL
@ -118,14 +118,13 @@ MCP for Unity connects your tools using two components:
#### To install via OpenUPM #### 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 2. Open a terminal (PowerShell, Terminal, etc.) and navigate to your Unity project directory
3. Run `openupm add com.coplaydev.unity-mcp` 3. Run `openupm add com.coplaydev.unity-mcp`
**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. **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). Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below).
<img width="648" height="599" alt="MCPForUnity-Readme-Image" src="https://github.com/user-attachments/assets/b4a725da-5c43-4bd6-80d6-ee2e3cca9596" /> <img width="648" height="599" alt="MCPForUnity-Readme-Image" src="https://github.com/user-attachments/assets/b4a725da-5c43-4bd6-80d6-ee2e3cca9596" />
@ -134,7 +133,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`. 1. In Unity, go to `Window > MCP for Unity`.
2. Click `Auto-Setup`. 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).*
<details><summary><strong>Client-specific troubleshooting</strong></summary> <details><summary><strong>Client-specific troubleshooting</strong></summary>
@ -147,7 +146,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: 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 (macOS):* `~/Library/Application Support/Claude/claude_desktop_config.json`
* *Claude Example (Windows):* `%APPDATA%\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. 2. **Edit the file** to add/update the `mcpServers` section, using the *exact* paths from Step 1.
@ -155,6 +154,23 @@ If Auto-Setup fails or you use a different client:
<details> <details>
<summary><strong>Click for Client-Specific JSON Configuration Snippets...</strong></summary> <summary><strong>Click for Client-Specific JSON Configuration Snippets...</strong></summary>
---
**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)** **VSCode (all OS)**
```json ```json
@ -181,7 +197,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L
"args": [ "args": [
"run", "run",
"--directory", "--directory",
"C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src", "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\UnityMCP\\UnityMcpServer\\src",
"server.py" "server.py"
] ]
} }
@ -202,7 +218,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L
"args": [ "args": [
"run", "run",
"--directory", "--directory",
"/usr/local/bin/UnityMCP/UnityMcpServer/src", "/Users/YOUR_USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src",
"server.py" "server.py"
] ]
} }
@ -211,7 +227,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:** **Linux:**
@ -223,7 +239,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L
"args": [ "args": [
"run", "run",
"--directory", "--directory",
"/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src", "/home/YOUR_USERNAME/.local/share/UnityMCP/UnityMcpServer/src",
"server.py" "server.py"
] ]
} }
@ -234,21 +250,7 @@ On Windows, set `command` to the absolute shim, e.g. `C:\\Users\\YOU\\AppData\\L
(Replace YOUR_USERNAME) (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 /[PATH_TO]/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
```
</details> </details>
--- ---
@ -261,58 +263,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. 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) 📝 ## Development & Contributing 🛠️
### 🔴 High Priority ### For Developers
- [ ] **Asset Generation Improvements** - Enhanced server request handling and asset pipeline optimization If you're contributing to MCP for Unity or want to test core changes, we have development tools to streamline your workflow:
- [ ] **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
<details open>
<summary><strong>✅ Completed Features<strong></summary>
- [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)).
</details>
### 🔬 Research & Exploration
- [ ] **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:
- **Development Deployment Scripts**: Quickly deploy and test your changes to MCP for Unity Bridge and Python Server - **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 - **Automatic Backup System**: Safe testing with easy rollback capabilities
- **Hot Reload Workflow**: Fast iteration cycle for core development - **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. 📖 **See [README-DEV.md](README-DEV.md)** for complete development setup and workflow documentation.
@ -321,15 +284,10 @@ If you\'re contributing to MCP for Unity or want to test core changes, we have d
Help make MCP for Unity better! Help make MCP for Unity better!
1. **Fork** the main repository. 1. **Fork** the main repository.
2. **Create a branch** (`feature/your-idea` or `bugfix/your-fix`). 2. **Create a branch** (`feature/your-idea` or `bugfix/your-fix`).
3. **Make changes.** 3. **Make changes.**
4. **Commit** (feat: Add cool new feature). 4. **Commit** (feat: Add cool new feature).
5. **Push** your branch. 5. **Push** your branch.
6. **Open a Pull Request** against the main branch. 6. **Open a Pull Request** against the main branch.
--- ---
@ -344,12 +302,18 @@ Help make MCP for Unity better!
- Check the status window: Window > MCP for Unity. - Check the status window: Window > MCP for Unity.
- Restart Unity. - Restart Unity.
- **MCP Client Not Connecting / Server Not Starting:** - **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 Server Path:** Double-check the --directory path in your MCP Client's JSON config. It must exactly match the installation location:
- **Verify uv:** Make sure `uv` is installed and working (pip show uv). - **Windows:** `%USERPROFILE%\AppData\Local\UnityMCP\UnityMcpServer\src`
- **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` - **macOS:** `~/Library/AppSupport/UnityMCP/UnityMcpServer\src`
- **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. - **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:** - **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.
</details> </details>