✨ Unity-MCP Pro is a high-performance Model Context Protocol (MCP) server for the Unity Editor that gives AI assistants and custom tools a reliable way to automate scenes, GameObjects, components, physics, and project workflows.
Created, maintained, and actively expanded by NishantJLU.
This repository is the primary home for the current Unity-MCP implementation, including the bridge workflow, automation surface, tooling, and ongoing product improvements.
- List and load scenes within the project
- Inspect scene settings and global configurations
- Open/save projects and manage asset database items
- Create GameObjects, Prefabs, Cameras, and Lights
- Reorder, rename, delete, parent, and toggle active states
- Manage Tags, Layers, and static flags for complex scene organization
- Add or remove components in real-time
- Read/write property values via C# Reflection (Deep Property Access)
- Inspect component metadata and state in the Inspector-equivalent view
- Capture live screenshots from the Editor/Game view
- Adjust camera properties, FOV, and post-processing for visual reasoning
- Automated scene auditing through visual feedback
- Main-Thread Dispatcher: Safely execute commands without crashing Unity
- Scene Graph Analytics: Structured JSON map of the entire object hierarchy
- Batch operations to minimize overhead and maximize execution speed
- Unity Editor (2021.3 LTS or later)
- Node.js (18+ recommended)
- npm or yarn package manager
-
Clone the repository
git clone https://github.com/NishantJLU/Unity-MCP.git cd Unity-MCP -
Install dependencies
npm install
-
Build the project
npm run build
-
Install the Unity Bridge
- Copy the
UnityScriptsfolder into your Unity project'sAssetsdirectory. - This adds the custom Editor Window and bridge listener to your project.
- Copy the
Point your MCP client to the built server entry (unity-mcp-server/index.js):
Windows:
{
"mcpServers": {
"UnityMCPPro": {
"command": "node",
"args": ["C:\\\\path\\\\to\\\\Unity-MCP\\\\unity-mcp-server\\\\index.js"]
}
}
}- Primary author and maintainer of Unity-MCP Pro: NishantJLU
- This repository reflects original work across the MCP server, C# bridge dispatcher, documentation, and automation capabilities.
-
Start the MCP server
npm start
-
Open Unity
-
Open the Unity MCP Pro Panel
- In Unity, go to Window > AI > Unity MCP Pro
- Click the ESTABLISH LINK button
- The status should change to
LINK_ESTABLISHED - The bridge communicates via a local high-performance HTTP listener.
Once the server is running and the Unity MCP panel is active, AI assistants can send structured commands directly into your Unity Editor workflow.
You can create new objects with custom settings such as:
- Name
- Primitive Type (Cube, Sphere, etc.)
- Position, Rotation, Scale
- Tag and Layer Example MCP tool usage:
create-gameobject({
name: "AI_Controlled_Cube",
primitiveType: "Cube",
position: { x: 0, y: 5, z: 0 },
tag: "Untagged"
});You can modify any component property via Reflection:
Transform & Physics:
- Adjust Rigidbody mass and drag
- Modify Transform properties precisely
- Toggle Gravity and Colliders
Lights & Rendering:
- Change Light intensity, color, and range
- Modify MeshRenderer materials and shaders
You can automate visual workflows with:
Screenshot Capture:
- Take a high-resolution snapshot of the current view
- Allow the AI to "see" the scene layout for aesthetic adjustments
- Audit UI placement and visual bugs
Unity-MCP Pro exposes 26 consolidated tools across Editor Automation, Game Master, Reflection Querying, and Script Generation:
create_unity_object: Spawns 3D primitives (Cube,Sphere,Capsule,Cylinder,Plane,Quad).update_unity_transform: Modifies position, rotation, and scale of objects.set_unity_material: Sets material color (RGBA) and smoothness.add_unity_component: Dynamically appends any component to a GameObject.set_unity_property: Modifies fields and properties reflectively.parent_unity_object: Adjusts hierarchy parent/child relationships.destroy_unity_object: Permanent undoable destruction of target objects.create_unity_ui: Builds UI Canvas overlays containing buttons, text, and images.set_unity_text: Sets contents of UI Text, TextMesh, or TextMeshPro components.get_unity_scene_graph: Returns a JSON tree of active GameObjects, tags, and states.list_unity_scene: Fast scan listing all object names in the scene.
take_unity_screenshot: Captures SceneView viewports and returns an inline Base64 PNG block directly to the visual LLM interface.
inspect_gameobject: Lists all components attached to a target GameObject.get_component_properties: Lists all public properties, fields, types, and active values.
instantiate_prefab: Spawns a prefab asset at a given coordinate using its project path (e.g.Assets/Prefabs/Player.prefab).save_scene/load_scene: Saves or opens.unityscene paths.
compile_csharp_script: Injects C# classes inheriting fromMonoBehaviourand compiles them instantly in the editor on the fly.
get_game_state: Exposes runtime clock and player state metadata.get_presets: Queries dynamic spawning presets from Resources.spawn_entity: Spawns capsule monsters or prop presets.trigger_world_event: Emits scene-wide events.broadcast_narrative: Appends visual messages.set_npc_dialogue: Alters NPC speech lines and moods.query_nearby_entities: Lists active entities in a spherical range.search_assets: Query expression search on the asset database.
unity-mcp-server/index.js: MCP server implementation (Node.js)UnityScripts/: C# bridge and Editor dispatcher logicsetup.bat: Windows automation helper for installation
npm run buildnpm testContributions are welcome. If you want to improve Unity-MCP Pro, open an issue or submit a pull request with a focused change.
Developed by NishantJLU