Unity MCP ✨
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.
Key Features 🚀
- 🗣️ 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.
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").
How It Works 🤔
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)]
Installation ⚙️
Note: The setup is constantly improving as we update the package. Check back if you randomly start to run into issues.
Prerequisites
- 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:
Step 1: Install the Unity Package (Bridge)
- 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 Claude or Auto 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
- Edit the file to add/update the
mcpServers section, using the exact paths from Step 1.
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)
Usage ▶️
- 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.
Contributing 🤝
Help make Unity MCP better!
- Fork the main repository.
- Create a branch (
feature/your-idea or bugfix/your-fix). - Make changes.
- Commit (feat: Add cool new feature).
- Push your branch.
- Open a Pull Request against the master branch.
Troubleshooting ❓
- 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.
License 📜
MIT License. See LICENSE file.
Acknowledgments 🙏
Thanks to the contributors and the Unity team.