[//]: # (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:

| | |
|:---------|:-------------|
| !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

---