[//]: # (Constants)
[license-link]: https://github.com/muammar-yacoob/unity-mcp/blob/main/LICENSE
[stars-link]: https://github.com/muammar-yacoob/unity-mcp/stargazers
[issues-link]: https://github.com/muammar-yacoob/unity-mcp/issues
[discord-link]: https://discord.gg/1424501956759523442
[npm-link]: https://www.npmjs.com/package/@spark-apps/unity-mcp
[mcp-link]: https://smithery.ai/server/@muammar-yacoob/unity-mcp
[sponsor-link]: https://github.com/sponsors/muammar-yacoob
Unity MCP
โจ What It Does
Unity MCP provides
real-time control of Unity Editor through the Model Context Protocol, allowing you to:
|
Feature
|
Description
|
|:---------|:-------------|
| !
Editor Control | Select, move, rotate, and scale objects with natural language |
| !
Batch Operations | Align, distribute, duplicate objects with undo support |
| !
Automated Testing | Enter play mode and run test scenarios programmatically |
| !
Scene Management | Load, save, inspect scene hierarchy in real-time |
๐ Quick Setup
$3
๐ Requirements
- Node.js >= 18.0.0 - Download
- Unity 2022.3 LTS or later - Download
- Claude Desktop or any MCP client - Download
---
๐ฅ Installation
๐ฆ Choose your installation method
Option 1: Claude Code (Recommended)
``bash
claude mcp add @spark-apps/unity-mcp
`
Option 2: Manual Installation
`bash
npm i -g @spark-apps/unity-mcp
`
Then add to your MCP client config:
- Windows %APPDATA%\\Claude\\claude_desktop_config.json
- macOS ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux ~/.config/Claude/claude_desktop_config.json
`json
{
"mcpServers": {
"unity-mcp": {"command": "npx", "args": ["-y", "@spark-apps/unity-mcp"]}
}
}
`
Restart your MCP client after installation.
---
๐ฎ Unity Editor Integration
โก Required one-time setup per Unity project
Why is this needed?
Unity MCP installs C# editor scripts into your Unity project that create an HTTP server on port 8080. The MCP tools communicate with Unity through this server.
Setup Steps:
1. Open your MCP client (e.g., Claude Desktop or Claude Code)
2. Tell Claude:
`
Setup Unity MCP in my project at /path/to/unity/project
`
3. This installs 4 C# scripts to Assets/Editor/UnityMCP/:
- MCPEditorServer.cs - HTTP server
- EditorCommandHandler.cs - Command processor with undo support
- PlayModeHandler.cs - Play mode automation
- SceneHandler.cs - Scene operations
4. Restart Unity Editor
5. Verify in Console: [Unity MCP] Server started on port 8080
Done! The MCP tools can now control Unity Editor via HTTP.
---
๐ ๏ธ Available Tools
๐ง View All Available Tools (19 tools)
Safe Operations (Read-only)
| Tool
| Description
|
|:------|:-------------|
| !Setup Unity MCP | Install editor integration into Unity project |
| !Select Objects | Select by name, tag, or pattern with framing |
| !Find Objects | Find by component type or pattern |
| !List Scenes | List all scenes in build settings |
| !Get Hierarchy | Get complete scene hierarchy |
| !Find In Scene | Find objects in current scene |
| !Play Mode Status | Get play mode status and logs |
Modifications (With Undo Support)
| Tool
| Description
|
|:------|:-------------|
| !Transform Objects | Move, rotate, scale objects |
| !Align Objects | Align left/right/top/bottom/center |
| !Distribute Objects | Distribute evenly along axis |
| !Duplicate Objects | Clone objects with undo support |
| !Enter Play Mode | Start play mode programmatically |
| !Exit Play Mode | Exit play mode programmatically |
| !Run Test | Execute automated test scenarios |
| !Set Time Scale | Slow motion or fast forward |
| !Load Scene | Load scene by name or index |
| !Save Scene | Save current or all scenes |
Destructive Operations (Use with Caution)
| Tool
| Description
|
|:------|:-------------|
| !Delete Objects | Delete objects with undo support |
| !Cleanup Scene | Remove missing scripts and empty objects |
---
๐ฌ Example Commands
๐ฏ Object Manipulation
- "Select all objects with tag 'Enemy' and align them horizontally"
- "Move the Player object to position (0, 5, 10)"
- "Distribute selected objects evenly along the x axis"
- "Find all objects with Camera component"
- "Duplicate selected object 5 times"
๐งช Automated Testing
- "Enter play mode and move Player to (10, 0, 0) for 5 seconds"
- "Set time scale to 0.5 for slow motion"
- "Run a test that destroys the Boss after 2 seconds"
- "Check play mode status and show test logs"
๐บ๏ธ Scene Operations
- "List all scenes in the project"
- "Load the MainMenu scene"
- "Show me the complete hierarchy of the current scene"
- "Find all objects with Rigidbody component"
- "Clean up scene by removing missing scripts"
---
๐ Troubleshooting
โ Common Issues
MCP Server Not Showing:
1. Verify Node.js is installed: node --version
2. Check config file path is correct
3. Ensure JSON syntax is valid
4. Restart MCP client completely
Unity Editor Not Responding:
1. Ensure Unity Editor is open
2. Check Assets/Editor/UnityMCP/ scripts are installed
3. Verify Console for [Unity MCP] Server started on port 8080
4. Check no errors in Unity Console
Port Already in Use:
1. Default port is 8080
2. Check what's using it: lsof -i :8080 (Mac/Linux) or netstat -ano | findstr :8080` (Windows)
3. Stop conflicting process or change port in Unity scripts
---
๐ Documentation
-
Unity Editor Scripting API
-
Model Context Protocol
-
Report Issues
---
๐ค Contributing
Contributions welcome! Focus areas:
- โ
Editor manipulation and automation
- โ
Testing workflows
- โ
Scene management
- โ
Bug fixes and improvements
Not in scope: Code generation (use
context7 MCP instead)
---
๐ License
MIT ยฉ
Muammar Yacoob
---
๐ If Unity MCP saves you time, show some love!
![Star on GitHub][stars-link]
![Sponsor][sponsor-link]
Built with โค๏ธ for game developers who want to automate repetitive tasks