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.
The Unity MCP Server provides a bidirectional communication channel between Unity (via C#) and a Python server, enabling:
- 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 project is perfect for developers who want to leverage LLMs to enhance their Unity projects or automate repetitive tasks.
- Unity 2020.3 LTS or newer
- Python 3.7 or newer
- uv package manager
If you're on Mac, please install uv as
brew install uvOn Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"and then add to your PATH:
set Path=%USERPROFILE%\.local\bin;%Path%On Linux
curl -LsSf https://astral.sh/uv/install.sh | shOtherwise, installation instructions are on their website: Install uv
-
Add the Unity Package
- Open Unity Package Manager (
Window > Package Manager) - Click the
+button and selectAdd package from git URL - Enter:
https://github.com/justinpbarnett/unity-mcp.git
- Open Unity Package Manager (
-
Set Up Python Environment
- Navigate to the Python directory in your project:
- If installed as a package:
Library/PackageCache/com.justinpbarnett.unity-mcp/Python - If installed locally:
Assets/unity-mcp/Python
- If installed as a package:
- Install dependencies:
uv venv uv pip install -e .
- Navigate to the Python directory in your project:
- Open the Unity MCP window (
Window > Unity MCP) - Click the "Configure Claude" button
- Follow the on-screen instructions to set up the integration
Alternatively, manually configure Claude Desktop:
- Go to Claude > Settings > Developer > Edit Config
- Edit
claude_desktop_config.jsonto include:
{
"mcpServers": {
"unityMCP": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/unity-mcp/Python",
"run",
"server.py"
]
}
}
}Replace /path/to/your/unity-mcp/Python with the actual path to the Unity MCP Python directory.
- Open the Unity MCP window (
Window > Unity MCP) - Click the "Configure Cursor" button
- Follow the on-screen instructions to set up the integration
Alternatively, go to Cursor Settings > MCP and paste this as a command:
uv --directory "/path/to/your/unity-mcp/Python" run server.pyReplace /path/to/your/unity-mcp/Python with the actual path to the Unity MCP Python directory.
- Start Claude Desktop or Cursor
- Launch your preferred tool
- The Unity MCP Server will automatically connect
To connect the MCP Server to tools like Claude Desktop or Cursor:
-
Open the Unity MCP Window
In Unity, go toWindow > Unity MCPto open the editor window. -
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.
-
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.
- Check the server status in the Unity MCP window. It will display:
If you prefer to manually configure your MCP client (like Claude Desktop or Cursor), you can create the configuration file yourself:
-
Locate the Configuration Directory
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
-
Create the Configuration File Create a JSON file with the following structure:
{ "mcpServers": { "unityMCP": { "command": "uv", "args": [ "--directory", "/path/to/your/unity-mcp/Python", "run", "server.py" ] } } } -
Find the Correct Python Path
- If installed as a package: Look in
Library/PackageCache/com.justinpbarnett.unity-mcp/Python - If installed locally: Look in
Assets/unity-mcp/Python
- If installed as a package: Look in
-
Verify Configuration
- Ensure the Python path points to the correct directory containing
server.py - Make sure the
uvcommand is available in your system PATH - Test the connection using the Unity MCP window
- Ensure the Python path points to the correct directory containing
Once configured, you can use the MCP Server to interact with LLMs directly from Unity or Python. Here are a couple of examples:
# Send a command to create a cube at position (0, 0, 0)
create_primitive(primitive_type="Cube", position=[0, 0, 0])# 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 file for detailed examples and instructions on extending functionality.
- 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.
We'd love your help to make the Unity MCP Server even better! Here's how to contribute:
-
Fork the Repository
Fork github.com/justinpbarnett/unity-mcp to your GitHub account. -
Create a Branch
git checkout -b feature/your-feature-name
-
Make Changes
Implement your feature or fix, following the project's coding standards (see HOW_TO_ADD_A_TOOL.md for guidance). -
Commit and Push
Use clear, descriptive commit messages:git commit -m "Add feature: your feature description" git push origin feature/your-feature-name -
Submit a Pull Request
Open a pull request to themasterbranch. Include a description of your changes and any relevant details.
For more details, check out CONTRIBUTING.md (to be created).
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.
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.pyin thePythondirectory). - Check
config.jsonfor correct port settings (default:unity_port: 6400,mcp_port: 6500). - Ensure
uvand dependencies are installed correctly.
- Verify the Python server is running (
-
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 or file a new issue.
Have questions or want to chat about the project? Reach out!
- X: @justinpbarnett
- GitHub: justinpbarnett
- Discord: Join our community (link coming soon!).
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!