• Node.js >= 18.0.0 - Download
• Unity 2022.3 LTS or later - Download
• Claude Desktop or any MCP client - Download

Option 1: Claude Code (Recommended)

claude mcp add @spark-apps/unity-mcp

Option 2: Manual Installation

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

{
  "mcpServers": {
    "unity-mcp": {"command": "npx", "args": ["-y", "@spark-apps/unity-mcp"]}
  }
}

Restart your MCP client after installation.

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.

Safe Operations (Read-only)

Tool	Description
	Install editor integration into Unity project
	Select by name, tag, or pattern with framing
	Find by component type or pattern
	List all scenes in build settings
	Get complete scene hierarchy
	Find objects in current scene
	Get play mode status and logs

Modifications (With Undo Support)

Tool	Description
	Move, rotate, scale objects
	Align left/right/top/bottom/center
	Distribute evenly along axis
	Clone objects with undo support
	Start play mode programmatically
	Exit play mode programmatically
	Execute automated test scenarios
	Slow motion or fast forward
	Load scene by name or index
	Save current or all scenes

Destructive Operations (Use with Caution)

Tool	Description
	Delete objects with undo support
	Remove missing scripts and empty objects

• "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"

• "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"

• "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"

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