Give your AI agent full control over Unity Editor.
77 tools · 7 resources · 1 prompt · Scene View screenshots · Script editing · Full editor automation
MCP Unity connects AI assistants — Claude, Cursor, OpenCode, Windsurf, GitHub Copilot, and any MCP-compatible client — directly to the Unity Editor.
Your agent can create GameObjects, modify scenes, run tests, capture screenshots, edit scripts, profile performance, and manage the entire editor lifecycle — all through natural language.
┌──────────────┐ stdio ┌────────────────┐ WebSocket ┌──────────────┐
│ MCP Client │ ◄────────────────► │ Node.js MCP │ ◄──────────────────► │ Unity Editor │
│ (Claude, │ │ Server (TS) │ ws://8090 │ (C# Tools) │
│ Cursor...) │ └────────────────┘ └──────────────┘
└──────────────┘
MCP Unity builds on CoderGamester/mcp-unity with production-ready reliability. The original works — this one works everywhere.
| Original | This fork | |
|---|---|---|
| Agent works without Unity focused | ❌ Timeout | ✅ MainThreadDispatcher |
| Scene View updates after mutations | ❌ Stale | ✅ Auto-repaint |
| Multi-object selection | ❌ Single only | ✅ Array + additive + frame |
| Object reference wiring | ❌ Manual | ✅ update_component resolves refs |
| Screenshots | ❌ | ✅ Scene View + Game View capture |
| Script read/write | ❌ | ✅ Create and edit .cs files |
| Profiler integration | 5 tools | 8 tools (recording, history, frame capture) |
| CI/CD | ❌ | ✅ GitHub Actions |
| Structured error messages | Ad-hoc | ✅ ToolErrors helper |
- Window → Package Manager → + → Add package from git URL
- Paste:
https://github.com/MaansenV/mcp-unity.git?path=/Packages/mcp-unity - Click Add
That's it. The Node server auto-installs on first use.
- Open Tools → MCP Unity → Server Window in Unity
- You should see
Connectedstatus on port8090 - Point your MCP client at the server (see client config below)
Once connected, ask your AI agent to:
"Create a 3D scene with a red cube on a green plane, position the camera to look at them, and take a screenshot"
"Find all GameObjects with a Rigidbody component and set their mass to 2.5"
"Read the PlayerController.cs script and add a double-jump mechanic"
"Run the test suite and tell me which tests fail"
"Open the profiler, capture 10 frames, and show me the memory allocation breakdown"
Your agent has 77 tools covering every aspect of Unity Editor — from scene management to shader inspection to prefab workflows.
Point your MCP client at the built Node server. The Unity Server Window (Tools → MCP Unity → Server Window) provides copy-paste snippets for all clients.
OpenCode
{
"mcp": {
"mcp-unity": {
"type": "local",
"command": ["node", "Packages/mcp-unity/Server~/build/index.js"],
"enabled": true
}
}
}Cursor / Windsurf / Claude Desktop / Generic
{
"mcpServers": {
"mcp-unity": {
"command": "node",
"args": ["/absolute/path/to/Packages/mcp-unity/Server~/build/index.js"]
}
}
}Claude Code
claude mcp add mcp-unity node /absolute/path/to/Packages/mcp-unity/Server~/build/index.jsScene Management — 9 tools
create_scene · load_scene · save_scene · delete_scene · unload_scene · get_scene_info · scene_set_active · scene_get_data · scene_list_opened
GameObjects — 8 tools
gameobject_create · gameobject_find · select_gameobject · update_gameobject · duplicate_gameobject · delete_gameobject · reparent_gameobject · get_gameobject
Transform — 4 tools
move_gameobject · rotate_gameobject · scale_gameobject · set_transform
Components — 4 tools
gameobject_component_get · gameobject_component_destroy · gameobject_component_list_all · update_component
Assets — 10 tools
assets_find · assets_find_built_in · assets_get_data · assets_create_folder · assets_copy · assets_move · assets_delete · assets_modify · assets_refresh · add_asset_to_scene
Materials & Shaders — 5 tools
create_material · assign_material · modify_material · get_material_info · assets_shader_list_all
Prefabs — 6 tools
create_prefab · prefab_create_from_scene · prefab_open · prefab_close · prefab_save · prefab_get_hierarchy
Screenshots — 2 tools ✨
screenshot_scene_view · screenshot_game_view
Scripts — 3 tools ✨
recompile_scripts · script_read · script_update_or_create
Profiler — 8 tools
profiler_start · profiler_stop · profiler_get_status · profiler_get_memory_stats · profiler_capture_frame · profiler_status · profiler_enable_recording · profiler_get_selected_frame
Editor & Console — 7 tools
execute_menu_item · editor_application_get_state · editor_application_set_state · editor_selection_get · get_console_logs · console_clear_logs · send_console_log
Reflection & Types — 3 tools
reflection_method_find · reflection_method_call · type_get_json_schema
Package Manager — 4 tools
add_package · package_list · package_remove · package_search
Object — 2 tools
object_get_data · object_modify
Testing & Batch — 2 tools
run_tests · batch_execute
77 tools total. See docs/TOOLS.md for full descriptions, parameters, and example prompts.
- Unity 2022.3 or newer
- Node.js 18 or newer
- An MCP client: OpenCode, Cursor, Windsurf, Claude Code, Claude Desktop, GitHub Copilot, Codex CLI, or any MCP-compatible tool
Adding a new tool follows a simple pattern — C# handler on the Unity side, TypeScript registration on the Node side.
Step-by-step: Add a tool
1. Unity (C#) — Create Editor/Tools/YourTool.cs:
namespace McpUnity.Tools
{
public class YourTool : McpToolBase
{
public YourTool()
{
Name = "your_tool";
Description = "Does something useful";
}
public override JObject Execute(JObject parameters)
{
// Your logic here
return new JObject { ["success"] = true, ["message"] = "Done!" };
}
}
}2. Register in Editor/UnityBridge/McpUnityServer.cs → RegisterTools():
AddTool(new YourTool());3. Node (TypeScript) — Create Server~/src/tools/yourTool.ts:
import { z } from 'zod';
export function registerYourTool(server: McpServer, mcpUnity: McpUnity, logger: Logger) {
server.tool('your_tool', 'Does something useful', {}, async () => {
return await mcpUnity.sendRequest({ method: 'your_tool', params: {} });
});
}4. Register in Server~/src/index.ts and run npm run build.
Tool names must match exactly between C# and TypeScript.
Packages/mcp-unity/
├── Editor/ C# Unity Editor package
│ ├── Tools/ Tool handlers (McpToolBase)
│ ├── Resources/ Resource handlers
│ ├── UnityBridge/ WebSocket server + routing
│ └── Utils/ MainThreadDispatcher, ToolErrors, Logger
├── Server~/ Node.js MCP server (TypeScript)
│ ├── src/index.ts Tool/resource/prompt registration
│ ├── src/tools/ Tool definitions (Zod schemas)
│ ├── src/__tests__/ Jest test suite (198 tests)
│ └── src/unity/ WebSocket client + connection
├── package.json Unity package manifest
└── server.json MCP registry metadata
- 198 tests — Unit tests for every tool, resource, and connection handler
- CI/CD — GitHub Actions runs build + test on every push
- Type-safe — Strict TypeScript on Node side, strongly-typed C# on Unity side
- Zero runtime dependencies on the Unity side — only editor APIs
| Problem | Solution |
|---|---|
| Agent times out | This fork fixes it — MainThreadDispatcher works without Unity focus. Verify port 8090 is open. |
unknown_method error |
Tool name mismatch between Node and Unity. Names must match exactly. |
| Scene View not updating | This fork auto-repaints after every mutation. |
| Package won't install | Git URL must include ?path=/Packages/mcp-unity |
| Node not found | Install Node.js 18+, ensure node and npm are on your PATH |
Contributions welcome! Here's how:
- Fork this repository
- Create a feature branch (
git checkout -b my-feature) - Make your changes — follow the Extending guide for new tools
- Test your changes (
cd Packages/mcp-unity/Server~ && npm test) - Submit a pull request
For architecture details, see AGENTS.md.