Update README.md
Justin P Barnett
GitHub
parent
48a89ca7d3
commit
0351e4fcf4
177
README.md
177
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
|
## 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
|
- **Asset Management**: Create, import, and manipulate Unity assets programmatically.
|
||||||
- Scene management and object manipulation
|
- **Scene Control**: Manage scenes, objects, and their properties.
|
||||||
- Material and script editing
|
- **Material Editing**: Modify materials and their properties.
|
||||||
- Editor control and automation
|
- **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.
|
This project is perfect for developers who want to leverage LLMs to enhance their Unity projects or automate repetitive tasks.
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
1. Import this package into your Unity project
|
Getting started is simple! Follow these steps to add the Unity MCP Server to your project:
|
||||||
2. Install Python requirements:
|
|
||||||
```bash
|
### Unity Package
|
||||||
cd Assets/MCPServer/Python
|
|
||||||
pip install -e .
|
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
|
## Usage
|
||||||
|
|
||||||
1. Set up MCP integration in Unity:
|
Once configured, you can use the MCP Server to interact with LLMs directly from Unity or Python. Here are a couple of examples:
|
||||||
- Open Window > Unity MCP
|
|
||||||
- Click the configuration button to set up integration with MCP clients like Claude Desktop or Cursor
|
|
||||||
|
|
||||||
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
|
```python
|
||||||
# Example: Create a new cube in the scene
|
# Send a command to create a cube at position (0, 0, 0)
|
||||||
create_primitive(primitive_type="Cube", position=[0, 0, 0])
|
create_primitive(primitive_type="Cube", position=[0, 0, 0])
|
||||||
|
```
|
||||||
|
|
||||||
# Example: Change material color
|
### 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])
|
set_material_color(material_name="MyMaterial", color=[1, 0, 0, 1])
|
||||||
```
|
```
|
||||||
|
|
||||||
## Adding New Tools
|
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.
|
||||||
|
|
||||||
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.
|
## Features
|
||||||
|
|
||||||
## Best Practices
|
- **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.
|
||||||
|
|
||||||
- Always validate parameters on both Python and C# sides
|
## Contributing
|
||||||
- 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
|
We’d love your help to make the Unity MCP Server even better! Here’s how to contribute:
|
||||||
|
|
||||||
Run Python tests with:
|
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
|
```bash
|
||||||
python -m unittest discover Assets/MCPServer/Python/tests
|
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
|
## Troubleshooting
|
||||||
|
|
||||||
- Check Unity Console for C# errors
|
Encountering issues? Here are some common fixes:
|
||||||
- Verify your MCP client (Claude Desktop, Cursor) is properly configured
|
|
||||||
- Check the MCP integration status in Window > Unity MCP
|
- **Unity Bridge Not Running**
|
||||||
- Check network connectivity between Unity and the MCP client
|
Ensure the Unity Editor is open and the MCP window is active. Restart Unity if needed.
|
||||||
- Ensure commands are properly registered in CommandRegistry.cs
|
|
||||||
- Verify Python tools are properly imported and registered
|
- **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!
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue