Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README-DEV.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Restores original files from backup.

Unity package cache is typically located at:
```
X:\UnityProject\Library\PackageCache\com.justinpbarnett.unity-mcp@1.0.0
X:\UnityProject\Library\PackageCache\com.coplaydev.unity-mcp@1.0.0
```

To find it:
Expand Down
87 changes: 39 additions & 48 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,28 @@
# Unity MCP ✨

#### Proudly sponsored and maintained by [Coplay](https://www.coplay.dev/?ref=unity-mcp), the AI assistant for Unity.

[![Discord](https://img.shields.io/badge/discord-join-red.svg?logo=discord&logoColor=white)](https://discord.gg/y4p8KfzrN4)
[![](https://img.shields.io/badge/Unity-000000?style=flat&logo=unity&logoColor=blue 'Unity')](https://unity.com/releases/editor/archive)
[![python](https://img.shields.io/badge/Python-3.12-3776AB.svg?style=flat&logo=python&logoColor=white)](https://www.python.org)
[![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction)
![GitHub commit activity](https://img.shields.io/github/commit-activity/w/justinpbarnett/unity-mcp)
![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/justinpbarnett/unity-mcp)
![GitHub commit activity](https://img.shields.io/github/commit-activity/w/CoplayDev/unity-mcp)
![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/CoplayDev/unity-mcp)
[![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)
[![](https://img.shields.io/badge/Sponsor-Coplay-red.svg 'Coplay')](https://www.coplay.dev/?ref=unity-mcp)

**Create your Unity apps with LLMs!**

Unity MCP 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/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.
Expand All @@ -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).
Expand All @@ -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)
Expand All @@ -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>

Expand All @@ -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)

Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -174,6 +177,7 @@ If Auto-Configure fails or you use a different client:
}
}
```

(Replace YOUR_USERNAME if using ~/bin)

**Linux:**
Expand All @@ -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
```
Expand All @@ -225,23 +229,26 @@ 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
- [ ] **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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

---

Expand All @@ -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

[![Star History Chart](https://api.star-history.com/svg?repos=CoplayDev/unity-mcp&type=Date)](https://www.star-history.com/#CoplayDev/unity-mcp&Date)

## Star History
## Sponsor

[![Star History Chart](https://api.star-history.com/svg?repos=justinpbarnett/unity-mcp&type=Date)](https://www.star-history.com/#justinpbarnett/unity-mcp&Date)
<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>
6 changes: 3 additions & 3 deletions UnityMcpBridge/Editor/Helpers/ServerInstaller.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ public static class ServerInstaller
{
private const string RootFolder = "UnityMCP";
private const string ServerFolder = "UnityMcpServer";
private const string BranchName = "master";
private const string GitUrl = "https://github.com/justinpbarnett/unity-mcp.git";
private const string BranchName = "main";
private const string GitUrl = "https://github.com/CoplayDev/unity-mcp.git";
private const string PyprojectUrl =
"https://raw.githubusercontent.com/justinpbarnett/unity-mcp/refs/heads/"
"https://raw.githubusercontent.com/CoplayDev/unity-mcp/refs/heads/"
+ BranchName
+ "/UnityMcpServer/src/pyproject.toml";

Expand Down
2 changes: 1 addition & 1 deletion UnityMcpBridge/Editor/Windows/UnityMcpEditorWindow.cs
Original file line number Diff line number Diff line change
Expand Up @@ -626,7 +626,7 @@ private string FindPackagePythonDirectory()
{
foreach (UnityEditor.PackageManager.PackageInfo package in request.Result)
{
if (package.name == "com.justinpbarnett.unity-mcp")
if (package.name == "com.coplaydev.unity-mcp")
{
string packagePath = package.resolvedPath;

Expand Down
4 changes: 2 additions & 2 deletions UnityMcpBridge/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "com.justinpbarnett.unity-mcp",
"version": "2.0.0",
"name": "com.coplaydev.unity-mcp",
"version": "1.0.0",
"displayName": "Unity MCP Bridge",
"description": "A bridge that manages and communicates with the sister application, Unity MCP Server, which allows for communications with MCP Clients like Claude Desktop or Cursor.",
"unity": "2020.3",
Expand Down
2 changes: 1 addition & 1 deletion deploy-dev.bat
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ echo.

:: Package cache location
echo Unity Package Cache Location:
echo Example: X:\UnityProject\Library\PackageCache\com.justinpbarnett.unity-mcp@1.0.0
echo Example: X:\UnityProject\Library\PackageCache\com.coplaydev.unity-mcp@1.0.0
set /p "PACKAGE_CACHE_PATH=Enter Unity package cache path: "

if "%PACKAGE_CACHE_PATH%"=="" (
Expand Down
Binary file added logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion restore-dev.bat
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ echo.

:: Package cache location
echo Unity Package Cache Location:
echo Example: X:\UnityProject\Library\PackageCache\com.justinpbarnett.unity-mcp@1.0.0
echo Example: X:\UnityProject\Library\PackageCache\com.coplaydev.unity-mcp@1.0.0
set /p "PACKAGE_CACHE_PATH=Enter Unity package cache path: "

if "%PACKAGE_CACHE_PATH%"=="" (
Expand Down