mcp-unity

MCP Unity Editor is an MCP server integration that bridges Unity Editor with a Node.js implementation of the MCP protocol. It exposes a set of Unity-scoped actions (like executing menu items, selecting objects, updating game objects and components, managing scenes and assets, and querying console logs) that can be driven by AI agents or external tooling. This enables AI assistants such as Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, and Google Antigravity to control and query a Unity project from outside the editor, facilitating automated scene setup, testing, and game object management within your Unity projects. To begin, ensure the MCP server is running locally and listen on the configured port, then send MCP requests to execute the available actions or query scene data through the Node.js server.

Available tools include commands to:

• execute_menu_item: run Unity menu items by name (e.g., Create Empty).
• select_gameobject: pick objects by path or instance ID.
• update_gameobject: modify core properties like name, tag, layer, active state, or create the object if missing.
• update_component: add or modify components and their fields on a GameObject.
• add_package: install Unity packages via the Package Manager.
• run_tests: execute Unity Test Runner tests.
• send_console_log: push messages to the Unity console.
• add_asset_to_scene: place assets from the AssetDatabase into the current scene.
• create_prefab: create a prefab with optional MonoBehaviour script and serialized field values.
• create_scene / load_scene / delete_scene / save_scene / get_scene_info / unload_scene: manage scenes lifecycle and information.
• get_gameobject / get_console_logs / recompile_scripts / duplicate_gameobject / delete_gameobject / reparent_gameobject / move_gameobject / rotate_gameobject / scale_gameobject: manipulate scene hierarchy and properties with detailed control.

To use the tools from code or prompt, point the MCP client at the running server and invoke the desired tool with the appropriate parameters described in the tool prompts above. The server translates these MCP requests into Unity editor actions via the Unity side integration, enabling automated workflows within your project.

Prerequisites:

• Unity Editor installed (any supported version for your project).
• Node.js installed (LTS recommended).
• Access to the MCP Unity repository and its Node.js server implementation.

1. Clone or download the MCP Unity repository.
2. Install Node dependencies for the MCP server (in the server directory):
   • npm install
3. Prepare configuration:
   • Ensure Node.js server entry point exists (e.g., server.js) and is configured to expose MCP endpoints.
4. Run the MCP server locally:
   • npm run start (or node server.js, depending on the repository setup)
5. Start Unity and load your project. Ensure the Unity project can reach the MCP server host and port configured in the environment or server settings.
6. (Optional) Configure IPC or network settings in your editor to use the MCP endpoint on localhost:5000 (or your chosen port).

Tips and common considerations:

• If you see connection errors, verify that the MCP server process is running and listening on the configured port. Check firewall rules or port conflicts.
• Environment variables can customize host/port and authentication if the MCP server supports it. Common vars include MCP_HOST and MCP_PORT.
• The tools require appropriate Unity permissions and may rely on the Unity Editor being active or specific scenes/assets being loaded.
• When using add_package or update_component, ensure you have proper project backup since changes can affect project structure.
• For large scene operations, prefer batch actions or save checkpoints to avoid data loss during automation.