|
|
|
|
@ -1,11 +1,15 @@
|
|
|
|
|
# Unity MCP ✨
|
|
|
|
|
|
|
|
|
|
#### Proudly sponsored and maintained by [Coplay](https://www.coplay.dev/?ref=unity-mcp), the AI assistant for Unity.
|
|
|
|
|
|
|
|
|
|
[](https://discord.gg/y4p8KfzrN4)
|
|
|
|
|
[](https://unity.com/releases/editor/archive)
|
|
|
|
|
[](https://www.python.org)
|
|
|
|
|
[](https://modelcontextprotocol.io/introduction)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
|
[](https://www.coplay.dev/?ref=unity-mcp)
|
|
|
|
|
|
|
|
|
|
**Create your Unity apps with LLMs!**
|
|
|
|
|
|
|
|
|
|
@ -13,14 +17,12 @@ Unity MCP acts as a bridge, allowing AI assistants (like Claude, Cursor) to inte
|
|
|
|
|
|
|
|
|
|
## 💬 Join Our Community
|
|
|
|
|
|
|
|
|
|
### [Discord](https://discord.gg/vhTUxXaqYr)
|
|
|
|
|
### [Discord](https://discord.gg/y4p8KfzrN4)
|
|
|
|
|
|
|
|
|
|
**Get help, share ideas, and collaborate with other Unity MCP developers!**
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Key Features 🚀
|
|
|
|
|
|
|
|
|
|
* **🗣️ Natural Language Control:** Instruct your LLM to perform Unity tasks.
|
|
|
|
|
@ -35,7 +37,7 @@ Unity MCP acts as a bridge, allowing AI assistants (like Claude, Cursor) to inte
|
|
|
|
|
|
|
|
|
|
* `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).
|
|
|
|
|
@ -62,7 +64,6 @@ Unity MCP connects your tools using two components:
|
|
|
|
|
|
|
|
|
|
### Prerequisites
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* **Git CLI:** For cloning the server code. [Download Git](https://git-scm.com/downloads)
|
|
|
|
|
* **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/)
|
|
|
|
|
* **Unity Hub & Editor:** Version 2020.3 LTS or newer. [Download Unity](https://unity.com/download)
|
|
|
|
|
@ -76,6 +77,7 @@ Unity MCP connects your tools using two components:
|
|
|
|
|
* [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>
|
|
|
|
|
|
|
|
|
|
@ -95,9 +97,8 @@ Unity MCP connects your tools using two components:
|
|
|
|
|
3. Ensure .NET compatibility settings are correct
|
|
|
|
|
4. Add `USE_ROSLYN` to Scripting Define Symbols
|
|
|
|
|
5. Restart Unity
|
|
|
|
|
|
|
|
|
|
**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 (Bridge)
|
|
|
|
|
|
|
|
|
|
@ -106,11 +107,13 @@ Unity MCP connects your tools using two components:
|
|
|
|
|
3. Click `+` -> `Add package from git URL...`.
|
|
|
|
|
4. Enter:
|
|
|
|
|
```
|
|
|
|
|
https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge
|
|
|
|
|
https://github.com/CoplayDev/unity-mcp.git?path=/UnityMcpBridge
|
|
|
|
|
```
|
|
|
|
|
5. Click `Add`.
|
|
|
|
|
6. The MCP Server should automatically be installed onto your machine as a result of this process.
|
|
|
|
|
|
|
|
|
|
**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
|
|
|
|
|
|
|
|
|
|
Connect your MCP Client (Claude, Cursor, etc.) to the Python server you installed in Step 1.
|
|
|
|
|
@ -121,13 +124,13 @@ Connect your MCP Client (Claude, Cursor, etc.) to the Python server you installe
|
|
|
|
|
|
|
|
|
|
1. In Unity, go to `Window > Unity MCP`.
|
|
|
|
|
2. Click `Auto Configure` on the IDE you uses.
|
|
|
|
|
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)*.
|
|
|
|
|
|
|
|
|
|
**Option B: Manual Configuration**
|
|
|
|
|
|
|
|
|
|
If Auto-Configure 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.
|
|
|
|
|
@ -174,6 +177,7 @@ If Auto-Configure fails or you use a different client:
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
(Replace YOUR_USERNAME if using ~/bin)
|
|
|
|
|
|
|
|
|
|
**Linux:**
|
|
|
|
|
@ -197,18 +201,18 @@ If Auto-Configure fails or you use a different client:
|
|
|
|
|
|
|
|
|
|
(Replace YOUR_USERNAME)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**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:**
|
|
|
|
|
|
|
|
|
|
```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
|
|
|
|
|
```
|
|
|
|
|
@ -225,12 +229,13 @@ 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`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
@ -238,10 +243,12 @@ claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/S
|
|
|
|
|
- [ ] **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
|
|
|
|
|
@ -254,6 +261,7 @@ claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/S
|
|
|
|
|
</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
|
|
|
|
|
@ -266,7 +274,7 @@ claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Roaming/Python/Python313/S
|
|
|
|
|
|
|
|
|
|
### Development Tools
|
|
|
|
|
|
|
|
|
|
If you're contributing to Unity MCP or want to test core changes, we have development tools to streamline your workflow:
|
|
|
|
|
If you\'re contributing to Unity MCP or want to test core changes, we have development tools to streamline your workflow:
|
|
|
|
|
|
|
|
|
|
- **Development Deployment Scripts**: Quickly deploy and test your changes to Unity MCP Bridge and Python Server
|
|
|
|
|
- **Automatic Backup System**: Safe testing with easy rollback capabilities
|
|
|
|
|
@ -289,8 +297,7 @@ Help make Unity MCP better!
|
|
|
|
|
|
|
|
|
|
5. **Push** your branch.
|
|
|
|
|
|
|
|
|
|
6. **Open a Pull Request** against the master branch.
|
|
|
|
|
|
|
|
|
|
6. **Open a Pull Request** against the main branch.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
@ -300,53 +307,37 @@ Help make Unity MCP better!
|
|
|
|
|
<summary><strong>Click to view common issues and fixes...</strong></summary>
|
|
|
|
|
|
|
|
|
|
- **Unity Bridge Not Running/Connecting:**
|
|
|
|
|
|
|
|
|
|
- Ensure Unity Editor is open.
|
|
|
|
|
|
|
|
|
|
- Check the status window: Window > Unity MCP.
|
|
|
|
|
|
|
|
|
|
- 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).
|
|
|
|
|
|
|
|
|
|
- **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.
|
|
|
|
|
|
|
|
|
|
- **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>
|
|
|
|
|
|
|
|
|
|
Still stuck? [Open an Issue](https://www.google.com/url?sa=E&q=https%3A%2F%2Fgithub.com%2Fjustinpbarnett%2Funity-mcp%2Fissues) or [Join the Discord](https://discord.gg/vhTUxXaqYr)!
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Contact 👋
|
|
|
|
|
|
|
|
|
|
- **justinpbarnett:** [X/Twitter](https://www.google.com/url?sa=E&q=https%3A%2F%2Fx.com%2Fjustinpbarnett)
|
|
|
|
|
- **scriptwonder**: [Email](mailto:swu85@ur.rochester.edu), [LinkedIn](https://www.linkedin.com/in/shutong-wu-214043172/)
|
|
|
|
|
|
|
|
|
|
Still stuck? [Open an Issue](https://github.com/CoplayDev/unity-mcp/issues) or [Join the Discord](https://discord.gg/y4p8KfzrN4)!
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## License 📜
|
|
|
|
|
|
|
|
|
|
MIT License. See [LICENSE](https://www.google.com/url?sa=E&q=https%3A%2F%2Fgithub.com%2Fjustinpbarnett%2Funity-mcp%2Fblob%2Fmaster%2FLICENSE) file.
|
|
|
|
|
MIT License. See [LICENSE](LICENSE) file.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Acknowledgments 🙏
|
|
|
|
|
|
|
|
|
|
Thanks to the contributors and the Unity team.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Star History
|
|
|
|
|
|
|
|
|
|
[](https://www.star-history.com/#justinpbarnett/unity-mcp&Date)
|
|
|
|
|
[](https://www.star-history.com/#CoplayDev/unity-mcp&Date)
|
|
|
|
|
|
|
|
|
|
## Sponsor
|
|
|
|
|
|
|
|
|
|
<p align="center">
|
|
|
|
|
<a href="https://www.coplay.dev/?ref=unity-mcp" target="_blank" rel="noopener noreferrer">
|
|
|
|
|
<img src="logo.png" alt="Coplay Logo" width="100%">
|
|
|
|
|
</a>
|
|
|
|
|
</p>
|
|
|
|
|
|
Marcus Sanatan
GitHub
