From 48a89ca7d3aa656a36556809da8a3351cbd63d5f Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 07:15:47 -0400 Subject: [PATCH 1/8] Added mit license --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ebeecf5 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Justin P Barnett + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From 0351e4fcf4288a23db4dbe71b863c6c4124acf10 Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 07:21:33 -0400 Subject: [PATCH 2/8] Update README.md --- README.md | 203 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 140 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 4798a46..10c728c 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,158 @@ -# Unity Model Context Protocol (MCP) Server +# Unity MCP Package -A bridge between Python and Unity that allows for programmatic control of the Unity Editor through Python scripts. +A Unity package that enables seamless communication between Unity and Large Language Models (LLMs) like Claude Desktop via the **Model Context Protocol (MCP)**. This server acts as a bridge, allowing Unity to send commands to and receive responses from MCP-compliant tools, empowering developers to automate workflows, manipulate assets, and control the Unity Editor programmatically. + +Welcome to the initial release of this open-source project! Whether you're looking to integrate LLMs into your Unity workflow or contribute to an exciting new tool, we’re thrilled to have you here. ## Overview -The Unity MCP Server provides a bidirectional communication channel between Python and the Unity Editor, enabling: +The Unity MCP Server provides a bidirectional communication channel between Unity (via C#) and a Python server, enabling: -- Creation and manipulation of Unity assets -- Scene management and object manipulation -- Material and script editing -- Editor control and automation +- **Asset Management**: Create, import, and manipulate Unity assets programmatically. +- **Scene Control**: Manage scenes, objects, and their properties. +- **Material Editing**: Modify materials and their properties. +- **Script Integration**: View, create, and update Unity scripts. +- **Editor Automation**: Control Unity Editor functions like undo, redo, play, and build. -This system is designed to make Unity Editor operations programmable through Python, allowing for more complex automation workflows and integrations. - -## Structure - -- **Editor/**: C# implementation of Unity-side command handlers - - **Commands/**: Command handlers organized by functionality - - **Models/**: Data models and contract definitions - - **Helpers/**: Utility classes for common operations - - **MCPServerWindow.cs**: Unity Editor window for controlling the MCP Server - - **UnityMCPBridge.cs**: Core communication bridge implementation - -- **Python/**: Python server implementation - - **tools/**: Python tool implementations that map to Unity commands - - **server.py**: FastAPI server implementation - - **unity_connection.py**: Communication layer for Unity connection +This project is perfect for developers who want to leverage LLMs to enhance their Unity projects or automate repetitive tasks. ## Installation -1. Import this package into your Unity project -2. Install Python requirements: - ```bash - cd Assets/MCPServer/Python - pip install -e . - ``` +Getting started is simple! Follow these steps to add the Unity MCP Server to your project: + +### Unity Package + +1. **Download the Package** + Add via the Unity package manager using this link + ```text + https://github.com/justinpbarnett/unity-mcp.git + ``` + +2. **Add to Unity** + - Open Unity and navigate to `Window > Package Manager`. + - Click the `+` button and select `Add package from disk...`. + - Locate the downloaded package and select the `package.json` file. + +### Python Environment + +1. **Prerequisites** + Ensure you have: + - **Python** (version 3.7 or higher) installed. Download it from [python.org](https://www.python.org/downloads/). + - **`uv`** installed for managing Python dependencies. Install it via: + ```bash + pip install uv + ``` + +2. **Set Up the Python Server** + - Navigate to the `Python` directory within the package (e.g., `Assets/MCPServer/Python`). + - Create a virtual environment and install dependencies: + ```bash + uv venv + uv pip install -e . + ``` + +## Configuration + +To connect the MCP Server to tools like Claude Desktop or Cursor: + +1. **Open the Unity MCP Window** + In Unity, go to `Window > Unity MCP` to open the editor window. + +2. **Configure Your Tools** + - In the Unity MCP window, you’ll see buttons to configure **Claude Desktop** or **Cursor**. + - Click the appropriate button and follow the on-screen instructions to set up the integration. + +3. **Verify Server Status** + - Check the server status in the Unity MCP window. It will display: + - **Unity Bridge**: Should show "Running" when active. + - **Python Server**: Should show "Connected" (green) when successfully linked. ## Usage -1. Set up MCP integration in Unity: - - Open Window > Unity MCP - - Click the configuration button to set up integration with MCP clients like Claude Desktop or Cursor +Once configured, you can use the MCP Server to interact with LLMs directly from Unity or Python. Here are a couple of examples: -2. The Unity Bridge will start automatically when the Unity Editor launches, and the Python server will be started by the MCP client when needed. +### Creating a Cube in the Scene -3. Use Python tools to control Unity through the MCP client: - ```python - # Example: Create a new cube in the scene - create_primitive(primitive_type="Cube", position=[0, 0, 0]) - - # Example: Change material color - set_material_color(material_name="MyMaterial", color=[1, 0, 0, 1]) - ``` - -## Adding New Tools - -See [HOW_TO_ADD_A_TOOL.md](HOW_TO_ADD_A_TOOL.md) for detailed instructions on extending the MCP Server with your own tools. - -## Best Practices - -- Always validate parameters on both Python and C# sides -- Use try-catch blocks for error handling in both environments -- Follow the established naming conventions (UPPER_SNAKE_CASE for commands, snake_case for Python tools) -- Group related functionality in appropriate tool modules and command handlers - -## Testing - -Run Python tests with: -```bash -python -m unittest discover Assets/MCPServer/Python/tests +```python +# Send a command to create a cube at position (0, 0, 0) +create_primitive(primitive_type="Cube", position=[0, 0, 0]) ``` +### Changing a Material’s Color + +```python +# Set a material’s color to red (RGBA: 1, 0, 0, 1) +set_material_color(material_name="MyMaterial", color=[1, 0, 0, 1]) +``` + +Explore more commands in the [HOW_TO_ADD_A_TOOL.md](HOW_TO_ADD_A_TOOL.md) file for detailed examples and instructions on extending functionality. + +## Features + +- **Bidirectional Communication**: Seamlessly send and receive data between Unity and LLMs. +- **Asset Management**: Import assets, instantiate prefabs, and create new prefabs programmatically. +- **Scene Control**: Open, save, and modify scenes, plus create and manipulate game objects. +- **Material Editing**: Apply and modify materials with ease. +- **Script Integration**: Create, view, and update C# scripts within Unity. +- **Editor Automation**: Automate Unity Editor tasks like building projects or entering play mode. + +## Contributing + +We’d love your help to make the Unity MCP Server even better! Here’s how to contribute: + +1. **Fork the Repository** + Fork [github.com/justinpbarnett/unity-mcp](https://github.com/justinpbarnett/unity-mcp) to your GitHub account. + +2. **Create a Branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +3. **Make Changes** + Implement your feature or fix, following the project’s coding standards (see [HOW_TO_ADD_A_TOOL.md](HOW_TO_ADD_A_TOOL.md) for guidance). + +4. **Commit and Push** + Use clear, descriptive commit messages: + ```bash + git commit -m "Add feature: your feature description" + git push origin feature/your-feature-name + ``` + +5. **Submit a Pull Request** + Open a pull request to the `master` branch. Include a description of your changes and any relevant details. + +For more details, check out [CONTRIBUTING.md](CONTRIBUTING.md) (to be created). + +## License + +This project is licensed under the **MIT License**. Feel free to use, modify, and distribute it as you see fit. See the full license [here](https://github.com/justinpbarnett/unity-mcp/blob/master/LICENSE). ## Troubleshooting -- Check Unity Console for C# errors -- Verify your MCP client (Claude Desktop, Cursor) is properly configured -- Check the MCP integration status in Window > Unity MCP -- Check network connectivity between Unity and the MCP client -- Ensure commands are properly registered in CommandRegistry.cs -- Verify Python tools are properly imported and registered \ No newline at end of file +Encountering issues? Here are some common fixes: + +- **Unity Bridge Not Running** + Ensure the Unity Editor is open and the MCP window is active. Restart Unity if needed. + +- **Python Server Not Connected** + - Verify the Python server is running (`python server.py` in the `Python` directory). + - Check `config.json` (in `Assets/MCPServer`) for correct port settings (default: `unity_port: 6400`, `mcp_port: 6500`). + - Ensure `uv` and dependencies are installed correctly. + +- **Configuration Issues with Claude Desktop or Cursor** + Confirm the paths and settings in the configuration dialog match your tool’s installation. + +For additional help, check the [issue tracker](https://github.com/justinpbarnett/unity-mcp/issues) or file a new issue. + +## Contact + +Have questions or want to chat about the project? Reach out! + +- **Email**: [barnett.justin.p@gmail.com](mailto:barnett.justin.p@gmail.com) +- **GitHub**: [justinpbarnett](https://github.com/justinpbarnett) +- **Discord**: Join our community (link coming soon!). + +## Acknowledgments + +A huge thanks to everyone who’s supported this project’s initial release. Special shoutout to Unity Technologies for inspiring tools that push creative boundaries, and to the open-source community for making projects like this possible. + +Happy coding, and enjoy integrating LLMs with Unity! From a7058a41f961cc35484ba2f4bf11bc14e40b9708 Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 07:34:04 -0400 Subject: [PATCH 3/8] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 10c728c..624894d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Unity MCP Package +![](https://youtu.be/dCC7QoV5a6E) + A Unity package that enables seamless communication between Unity and Large Language Models (LLMs) like Claude Desktop via the **Model Context Protocol (MCP)**. This server acts as a bridge, allowing Unity to send commands to and receive responses from MCP-compliant tools, empowering developers to automate workflows, manipulate assets, and control the Unity Editor programmatically. Welcome to the initial release of this open-source project! Whether you're looking to integrate LLMs into your Unity workflow or contribute to an exciting new tool, we’re thrilled to have you here. From 129fc8319469c9bcfda5be3ae94d69cc6b1a9d48 Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 07:35:59 -0400 Subject: [PATCH 4/8] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 624894d..d10fcd8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Unity MCP Package -![](https://youtu.be/dCC7QoV5a6E) +![Creating a Mario Clone](https://youtu.be/dCC7QoV5a6E) A Unity package that enables seamless communication between Unity and Large Language Models (LLMs) like Claude Desktop via the **Model Context Protocol (MCP)**. This server acts as a bridge, allowing Unity to send commands to and receive responses from MCP-compliant tools, empowering developers to automate workflows, manipulate assets, and control the Unity Editor programmatically. From 7c2bd289a903f7d946bed2522d8550da571ac6e6 Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 07:36:58 -0400 Subject: [PATCH 5/8] Update README.md --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index d10fcd8..10c728c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Unity MCP Package -![Creating a Mario Clone](https://youtu.be/dCC7QoV5a6E) - A Unity package that enables seamless communication between Unity and Large Language Models (LLMs) like Claude Desktop via the **Model Context Protocol (MCP)**. This server acts as a bridge, allowing Unity to send commands to and receive responses from MCP-compliant tools, empowering developers to automate workflows, manipulate assets, and control the Unity Editor programmatically. Welcome to the initial release of this open-source project! Whether you're looking to integrate LLMs into your Unity workflow or contribute to an exciting new tool, we’re thrilled to have you here. From 208f8eca67ffcf051fc1e8872190cb1f86e97c0b Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 08:01:13 -0400 Subject: [PATCH 6/8] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 10c728c..f3be856 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Unity MCP Package +![Making a Mario Clone](https://vrcreators.b-cdn.net/mario_clone_launch.gif) + A Unity package that enables seamless communication between Unity and Large Language Models (LLMs) like Claude Desktop via the **Model Context Protocol (MCP)**. This server acts as a bridge, allowing Unity to send commands to and receive responses from MCP-compliant tools, empowering developers to automate workflows, manipulate assets, and control the Unity Editor programmatically. Welcome to the initial release of this open-source project! Whether you're looking to integrate LLMs into your Unity workflow or contribute to an exciting new tool, we’re thrilled to have you here. From bb0d847331a9d7b120c4ef85196f9c5ca76ae356 Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 08:02:07 -0400 Subject: [PATCH 7/8] Update README.md --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index f3be856..10c728c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Unity MCP Package -![Making a Mario Clone](https://vrcreators.b-cdn.net/mario_clone_launch.gif) - A Unity package that enables seamless communication between Unity and Large Language Models (LLMs) like Claude Desktop via the **Model Context Protocol (MCP)**. This server acts as a bridge, allowing Unity to send commands to and receive responses from MCP-compliant tools, empowering developers to automate workflows, manipulate assets, and control the Unity Editor programmatically. Welcome to the initial release of this open-source project! Whether you're looking to integrate LLMs into your Unity workflow or contribute to an exciting new tool, we’re thrilled to have you here. From 0b3802b5e4f067ac10f7e2cec0df71867be9130d Mon Sep 17 00:00:00 2001 From: Justin P Barnett <42453910+justinpbarnett@users.noreply.github.com> Date: Tue, 18 Mar 2025 09:45:22 -0400 Subject: [PATCH 8/8] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10c728c..6077d3a 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ For additional help, check the [issue tracker](https://github.com/justinpbarnett Have questions or want to chat about the project? Reach out! -- **Email**: [barnett.justin.p@gmail.com](mailto:barnett.justin.p@gmail.com) +- **X**: [@justinpbarnett](https://x.com/justinpbarnett) - **GitHub**: [justinpbarnett](https://github.com/justinpbarnett) - **Discord**: Join our community (link coming soon!).