Connect your Unity Editor to LLMs using the Model Context Protocol.
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.
- 🗣️ Natural Language Control: Instruct your LLM to perform Unity tasks.
- 🛠️ Powerful Tools: Manage assets, scenes, materials, scripts, and editor functions.
- 🤖 Automation: Automate repetitive Unity workflows.
- 🧩 Extensible: Designed to work with various MCP Clients.
Expand for Available Tools...
Your LLM can use functions like:
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_scene: Manages scenes (load, save, create, get hierarchy, etc.).manage_asset: Performs asset operations (import, create, modify, delete, etc.).manage_gameobject: Manages GameObjects: create, modify, delete, find, and component operations.execute_menu_item: Executes a menu item via its path (e.g., "File/Save Project").
Unity MCP connects your tools using two components:
- Unity MCP Bridge: A Unity package running inside the Editor. (Installed via Package Manager).
- Unity MCP Server: A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed manually).
Flow: [Your LLM via MCP Client] <-> [Unity MCP Server (Python)] <-> [Unity MCP Bridge (Unity Editor)]
Note: The setup is constantly improving as we update the package. Check back if you randomly start to run into issues.
Click to view required software...
- Git CLI: For cloning the server code. Download Git
- Python: Version 3.12 or newer. Download Python
- Unity Hub & Editor: Version 2020.3 LTS or newer. Download Unity
- uv (Python package manager):
pip install uv # Or see: https://docs.astral.sh/uv/getting-started/installation/ - An MCP Client:
- Claude Desktop
- Cursor
- (Others may work with manual config)
- Open your Unity project.
- Go to
Window > Package Manager. - Click
+->Add package from git URL.... - Enter:
https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge - Click
Add. - The MCP Server should automatically be installed onto your machine as a result of this process.
Connect your MCP Client (Claude, Cursor, etc.) to the Python server you installed in Step 1.
Option A: Auto-Configure (Recommended for Claude/Cursor)
- In Unity, go to
Window > Unity MCP. - Click
Auto Configure ClaudeorAuto Configure Cursor. - 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:
- 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
- Claude Example (macOS):
- Edit the file to add/update the
mcpServerssection, using the exact paths from Step 1.
Click for OS-Specific JSON Configuration Snippets...
Windows:
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": [
"run",
"--directory",
"C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src",
"server.py"
]
}
// ... other servers might be here ...
}
}(Remember to replace YOUR_USERNAME and use double backslashes \)
macOS:
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": [
"run",
"--directory",
"/usr/local/bin/UnityMCP/UnityMcpServer/src",
"server.py"
]
}
// ... other servers might be here ...
}
}(Replace YOUR_USERNAME if using ~/bin)
Linux:
{
"mcpServers": {
"UnityMCP": {
"command": "uv",
"args": [
"run",
"--directory",
"/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src",
"server.py"
]
}
// ... other servers might be here ...
}
}(Replace YOUR_USERNAME)
-
Open your Unity Project. The Unity MCP Bridge (package) should connect automatically. Check status via Window > Unity MCP.
-
Start your MCP Client (Claude, Cursor, etc.). It should automatically launch the Unity MCP Server (Python) using the configuration from Installation Step 3.
-
Interact! Unity tools should now be available in your MCP Client.
Example Prompt:
Create a 3D player controller.
Help make Unity MCP better!
-
Fork the main repository.
-
Create a branch (
feature/your-ideaorbugfix/your-fix). -
Make changes.
-
Commit (feat: Add cool new feature).
-
Push your branch.
-
Open a Pull Request against the master branch.
Click to view common issues and fixes...
-
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).
-
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.
Still stuck? Open an Issue.
MIT License. See LICENSE file.
- X/Twitter: @justinpbarnett
Thanks to the contributors and the Unity team.