Unity Editor MCP

⚠️This project is in beta and under heavy development.Features and APIs may change. Use at your own discretion.

Unity Editor MCP (Model Context Protocol) enables AI assistants like Claude and Cursor to interact directly with the Unity Editor, allowing for AI-assisted game development and automation.

- 🎮 GameObject Management: Create primitives, modify transforms, manage hierarchy, and delete objects
- 🔧 Component System: Add, remove, modify, and list components on GameObjects with full property control
- 🎭 Prefab Workflow: Complete prefab mode editing - open, modify, save, and exit with override management
- 🔍 Smart Search: Find GameObjects by name, tag, layer, or component type with exact/partial matching
- 📊 Scene Analysis: Analyze scene composition, component statistics, and prefab connections
- 🎯 Component Inspection: Get component values, find objects by component, trace references between objects
- 🎬 Scene Control: Create, load, save scenes, manage build settings, and work with multiple scenes
- 🏃 Play Mode Testing: Start, pause, and stop play mode, check editor state and compilation status
- 🖼️ Screenshot Capture: Take screenshots of Game View or Scene View with analysis capabilities
- 🎨 Asset Management: Create and modify prefabs, materials, scripts with comprehensive property control
- 🖱️ UI Automation: Interact with Unity UI elements programmatically for testing and automation
- 📝 Console Integration: Read Unity console logs filtered by type with enhanced debugging features
- 🔄 Editor Operations: Refresh assets, execute menu items, and trigger recompilation

- ✅ Unity 2020.3 LTS or newer
- ✅ Node.js 18.0.0 or newer
- ✅ Claude Desktop or Cursor
- OpenWindow → Package Manager
- Click"+"→"Add package from git URL..."
- Paste:https://github.com/ozankasikci/unity-editor-mcp.git?path=unity-editor-mcp
- ClickAdd

✨ Unity will automatically start the MCP bridge. It uses port 6400 when available and falls back to a free local port when multiple Unity instances are open.

- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "unity-editor-mcp": { "command": "npx", "args": ["unity-editor-mcp@latest"] } } }

Add the same configuration to Cursor's MCP settings
- Restart your MCP client(Claude Desktop or Cursor)
- Check Unity Console for:[Unity Editor MCP] Client connected
- You're ready to go! 🎮

Unity Editor MCP now auto-discovers running Unity projects. Each Unity Editor instance writes an internal runtime registry entry under~/.unity-editor-mcp/instances, including its project path, process ID, port, Unity version, package version, workspace ID, Git worktree metadata, and heartbeat timestamp. You do not edit this file.

When the Node MCP server starts, it selects the Unity instance in this order:
- UNITY_PORTor--port, if explicitly provided
- UNITY_MCP_INSTANCE_IDor--instance
- UNITY_PROJECT_PATH,UNITY_MCP_PROJECT_PATH, or--project
- UNITY_MCP_WORKSPACE_IDor--workspace-id
- the Unity project inferred from the current working directory
- the stable workspace ID inferred from the current working directory
- the only live Unity MCP instance, if exactly one exists

For Git worktrees, the workspace ID is stored in Git's private worktree metadata viagit rev-parse --git-path unity-editor-mcp/workspace-id. For non-Git projects it is stored underLibrary/UnityEditorMCP/workspace-id. It is not written to tracked Unity project files.

If the server infers a local Unity project/workspace from the current working directory, it requires an exact project or workspace match and does not use the single-live-instance fallback. If related worktrees from the same Git repository are open but none match the current worktree, it fails closed with aWORKTREE_MISMATCHcandidate list instead of connecting silently. To restore the old convenience fallback explicitly, setUNITY_MCP_ALLOW_SINGLE_INSTANCE_FALLBACK=trueor pass--allow-single-instance-fallback.

To inspect discovery without starting an MCP session:

unity-editor-mcp doctor unity-editor-mcp doctor --project /path/to/UnityProject unity-editor-mcp doctor --workspace-id <workspace-id> unity-editor-mcp doctor --instance <instance-id> unity-editor-mcp doctor --allow-single-instance-fallback unity-editor-mcp doctor --json

Unity Editor MCP provides63 comprehensive toolsacross 11 categories for complete Unity Editor automation:

- ping- Test connection to Unity Editor and verify server status
- read_logs- Read Unity console logs with filtering by type (Log, Warning, Error, etc.)
- refresh_assets- Refresh Unity assets and optionally wait for compilation to settle

- create_gameobject- Create GameObjects with primitives, transforms, tags, and layers
- find_gameobject- Find GameObjects by name, tag, layer with pattern matching
- modify_gameobject- Modify GameObject properties (transform, name, active state, parent, etc.)
- delete_gameobject- Delete single or multiple GameObjects with optional child handling
- get_hierarchy- Get complete scene hierarchy with components and depth control

- add_component- Add Unity components to GameObjects with initial property values
- remove_component- Remove components from GameObjects with safety checks (prevents Transform removal)
- modify_component- Modify component properties with support for nested properties using dot notation
- list_components- List all components on a GameObject with type information and removability status
- get_component_types- Discover available component types with filtering by category and addability

- create_scene- Create new scenes with build settings integration and auto-loading
- load_scene- Load existing scenes in Single or Additive mode
- save_scene- Save current scene with Save As functionality
- list_scenes- List all scenes in project with filtering and build settings info
- get_scene_info- Get detailed scene information including GameObject counts

- get_gameobject_details- Deep inspection of GameObjects with component details and hierarchy
- analyze_scene_contents- Comprehensive scene statistics, composition, and performance metrics
- get_component_values- Get all properties and values of specific components with metadata
- find_by_component- Find GameObjects by component type with scope filtering (scene/prefabs/all)
- get_object_references- Analyze references between objects including hierarchy and asset connections

- create_prefab- Create prefabs from GameObjects or empty templates with overwrite options
- modify_prefab- Modify existing prefabs with property changes and instance updates
- instantiate_prefab- Instantiate prefabs in scenes with transform and parenting options
- open_prefab- Open prefabs in Unity's prefab mode for detailed editing with focus and isolation
- exit_prefab_mode- Exit prefab mode with optional save/discard changes
- save_prefab- Save prefab changes in prefab mode or apply instance overrides to prefab assets
- create_material- Create new materials with shader assignment and property configuration
- modify_material- Modify existing materials with shader changes and property updates
- manage_asset_import_settings- Manage Unity asset import settings (get, modify, apply presets, reimport)
- manage_asset_database- Manage Unity Asset Database operations (find, info, create folders, move, copy, delete, refresh)
- analyze_asset_dependencies- Analyze Unity asset dependencies (get dependencies, dependents, circular deps, unused assets, size impact)

- create_script- Create new C# scripts with templates and namespace management
- read_script- Read script file contents with syntax highlighting information
- update_script- Modify existing scripts with content replacement and validation
- delete_script- Delete script files with dependency checking and confirmation
- list_scripts- List all scripts in project with filtering and metadata
- validate_script- Validate script syntax and check for compilation errors

- play_game- Start Unity play mode for testing and interaction
- pause_game- Pause or resume Unity play mode
- stop_game- Stop Unity play mode and return to edit mode
- get_editor_state- Get current Unity editor state (play mode, pause, compilation status)

- find_ui_elements- Locate UI elements in scene hierarchy with filtering
- click_ui_element- Simulate clicking on UI elements (buttons, toggles, etc.)
- get_ui_element_state- Get detailed UI element state and interaction capabilities
- set_ui_element_value- Set values for UI input elements (sliders, input fields, etc.)
- simulate_ui_input- Execute complex UI interaction sequences

- execute_menu_item- Execute Unity menu items programmatically with safety checks
- clear_console- Clear Unity console logs with optional filtering
- enhanced_read_logs- Advanced log reading with search, filtering, and export capabilities
- capture_screenshot- Take screenshots of Game View or Scene View with custom resolution and encoding
- analyze_screenshot- Analyze screenshot content with basic image analysis capabilities

Editor Control & Automation (9 tools)

- manage_tags- Manage Unity project tags (add, remove, list)
- manage_layers- Manage Unity project layers (add, remove, list, convert index/name)
- manage_selection- Manage Unity Editor selection (get, set, clear, get details)
- manage_windows- Manage Unity Editor windows (list, focus, get state)
- manage_tools- Manage Unity Editor tools and plugins (list, activate, deactivate, refresh)
- start_compilation_monitoring- Start monitoring Unity compilation with real-time error detection
- stop_compilation_monitoring- Stop compilation monitoring and get final status
- get_compilation_state- Get current Unity compilation state and errors
- wait_for_compilation- Wait for Unity compilation/domain reload to settle and return final messages

If you see "Port 6400 is already in use":
- This is expected when another Unity instance already owns the default port
- The package will fall back to an available local port automatically
- Rununity-editor-mcp doctorto see which project and port will be selected
- Ensure Unity Editor is running with the package installed
- Check the Unity console for error messages
- Verify the Node.js server is running
- Check your MCP client configuration path is absolute
- Ensure you have Node.js 18+ installed:node --version
- Runnpm installin the mcp-server directory
- Check for any error messages in the console

SeeCONTRIBUTING.mdfor development guidelines.

The intelligent MCP server for AI-assisted Godot 4 development. 35 tools for spatial intelligence, code understanding, flow tracing, and visual debugging. 22 free, full suite $19.