{"id":32514054,"url":"https://github.com/zoucdr/unity3d-mcp","last_synced_at":"2026-06-05T17:02:39.064Z","repository":{"id":317345709,"uuid":"1066972141","full_name":"zoucdr/unity3d-mcp","owner":"zoucdr","description":"✅The Unity3d MCP tool system fully supports editor operation and scalability.(Support execution of C# code without the need for recompilation!)","archived":false,"fork":false,"pushed_at":"2026-03-05T10:54:17.000Z","size":21195,"stargazers_count":41,"open_issues_count":4,"forks_count":5,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-05T14:53:25.437Z","etag":null,"topics":["ai","figma","mcp","ugui","unity","unity3d"],"latest_commit_sha":null,"homepage":"https://zoucdr.github.io/unity3d-mcp/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zoucdr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T07:55:48.000Z","updated_at":"2026-03-05T11:02:36.000Z","dependencies_parsed_at":"2025-10-16T06:24:52.016Z","dependency_job_id":null,"html_url":"https://github.com/zoucdr/unity3d-mcp","commit_stats":null,"previous_names":["zouhunter/unity3d-mcp","zoucdr/unity3d-mcp"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/zoucdr/unity3d-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoucdr%2Funity3d-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoucdr%2Funity3d-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoucdr%2Funity3d-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoucdr%2Funity3d-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoucdr","download_url":"https://codeload.github.com/zoucdr/unity3d-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoucdr%2Funity3d-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33951164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","figma","mcp","ugui","unity","unity3d"],"created_at":"2025-10-27T23:17:10.284Z","updated_at":"2026-06-05T17:02:39.047Z","avatar_url":"https://github.com/zoucdr.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"**English** | [中文](README.zh-CN.md)\n\n---\n\n# Unity3d MCP Documentation\n\n![Unity3d MCP](docs/unity3d-mcp.png)\n\n## Table of Contents\n1. [System Overview](#system-overview)\n2. [Architecture](#architecture)\n3. [Source Code](#source-code)\n4. [Usage](#usage)\n5. [Agent Skills Module](#agent-skills-module)\n6. [Innovation](#innovation)\n7. [Technical Features](#technical-features)\n8. [API Reference](#api-reference)\n9. [Troubleshooting](#troubleshooting)\n\n---\n\n## System Overview\n\n*Unity3d MCP — Bridging AI and Unity for intelligent game development*\n\nUnity3d MCP (Model Context Protocol) is an AI–Unity integration system that connects AI assistants (e.g. Cursor, Claude, Trae) with the Unity Editor via a built-in MCP server, enabling an AI-driven Unity workflow.\n\n### Core Value\n- **AI-driven development**: Control the Unity Editor with natural language\n- **Seamless integration**: Works with mainstream AI clients without changing your workflow\n- **Rich tooling**: 40+ tools covering the full Unity development pipeline\n- **High performance**: HTTP-based communication\n- **Extensible**: Modular design for easy extension\n- **Zero config**: Built-in MCP server inside Unity, no external dependencies\n\n### System Components\n- **Built-in MCP Server** (C#): MCP protocol server inside the Unity Editor\n- **Unity Package** (C#): Full Unity Editor plugin\n- **Tool ecosystem**: 40+ Unity development tools\n- **Protocol**: HTTP + JSON-RPC 2.0\n\n---\n\n## Architecture\n\n### Overall Architecture\n\nLayers (top to bottom):\n\n1. **AI client layer**: Cursor, Claude, Trae, etc.\n2. **MCP protocol layer**: Unity built-in MCP server\n3. **Communication layer**: HTTP (configurable port, default 8000) + JSON-RPC 2.0\n4. **Unity Editor layer**: Unity Editor + Unity API\n5. **Tool layer**: 40+ tools + message-queue execution engine\n\n#### Architecture Diagram\n\n![Unity3d MCP Architecture](docs/architecture.png)\n\n*Figure 1: Data flow from AI clients to the Unity Editor*\n\n#### Data Flow\n\n![Unity3d MCP Data Flow](docs/data_flow_graph.png)\n\n*Figure 2: Flow from AI instructions to Unity execution*\n\n### Design Principles\n\n#### 1. Two-tier call architecture\n```\nAI client → FacadeTools → MethodTools → Unity API\n```\n\n- **FacadeTools**: `async_call` and `batch_call`\n- **MethodTools**: 40+ methods, invoked only via FacadeTools\n\n#### 2. State-tree execution engine\n- State-based routing\n- Parameter validation and type conversion\n- Unified error handling\n\n#### 3. Connection management\n- Configurable port (default 8000)\n- Message queue processing\n- Main-thread–safe execution\n\n---\n\n## Source Code\n\n### 1. Unity MCP server (C#)\n\n#### Main files\n```\nunity-package/Editor/Connect/\n├── McpService.cs\n├── McpServiceStatusWindow.cs\n└── McpServiceGUI.cs\n```\n\n#### Components\n- **McpService.cs**: HTTP listener, MCP request handling\n- **Message queue**: EnqueueTask / ProcessMessageQueue, main-thread execution\n- **Tool discovery**: DiscoverTools, reflection-based registration of async_call / batch_call\n\n### 2. Unity tool package (C#)\n\n#### Structure\n- **Runtime**: StateTreeContext\n- **Editor/Executer**: AsyncCall, BatchCall, ToolsCall, CoroutineRunner, McpTool, StateMethodBase, IToolMethod, etc.\n- **Editor/StateTree**: StateTree, StateTreeBuilder\n- **Editor/Selector**: HierarchySelector, ProjectSelector, IObjectSelector\n- **Editor/Tools**: Hierarchy, ResEdit, Console, RunCode, UI, Storage, etc.\n- **Editor/GUI**: McpServiceGUI, McpDebugWindow\n\n### 3. Tool categories\n\n1. **Hierarchy**: hierarchy_create, hierarchy_search, hierarchy_apply  \n2. **ResEdit**: edit_gameobject, edit_component, edit_material, edit_texture, …  \n3. **Project**: project_search, project_operate  \n4. **UI**: ugui_layout, ui_rule_manage, figma_manage  \n5. **Console**: console_read, console_write  \n6. **RunCode**: code_runner, python_runner  \n7. **Editor**: base_editor, manage_package, gameplay, object_delete  \n8. **Storage**: prefers, source_location  \n9. **Network**: request_http  \n\n---\n\n## Usage\n\n### 1. Requirements\n\n- Unity 2020.3+ (recommended 2022.3.61f1c1)\n- MCP-capable AI client (Cursor / Claude / Trae)\n- Windows / macOS / Linux\n\nNo extra Python or external dependencies for the Unity package.\n\n### 2. Configuration\n\n#### MCP client config\nAdd to your AI client MCP config (e.g. `~/.cursor/mcp.json`, Claude/VS/Trae equivalents):\n\n```json\n{\n  \"mcpServers\": {\n    \"unity3d-mcp\": {\n      \"url\": \"http://localhost:8000\"\n    }\n  }\n}\n```\n\n#### Unity Editor\n\n- **MCP Settings** (`Edit → Project Settings → MCP`): connection toggle, tool list, port (default 8000), log level, UI/Figma settings.\n- **MCP Debug Window** (`Window → MCP → Debug Window`): call history, re-run, filter, export logs.\n\n### 3. Agent skills and token saving\n\nTo avoid large context from full MCP tool lists and schemas, the project provides an **Agent Skills** module (see [Agent Skills Module](#agent-skills-module)). Reference `demo/.cursor/skills` SKILL.md files in Cursor Rules or Agent config so the agent loads only the needed skill docs and then calls MCP, reducing token usage.\n\n### 4. Quick start\n\n1. Import the Unity package and open the project.\n2. The built-in MCP server starts automatically (default port 8000).\n3. In the AI client, try: *\"Create a Cube named Player\"*.\n\n### 5. Examples\n\n- Create GameObject: *\"Create a Cube named Player\"*\n- Batch: *\"Create 5 Enemy objects at (0,0,0), (1,0,0), …\"*\n- Resources: *\"Download a random image and apply it to an Image component\"*\n\n### 6. Advanced\n\n- **Custom tools**: Add classes under `unity-package/Editor/Tools/`, inherit `StateMethodBase` or `IToolMethod`, use `ToolNameAttribute`; Unity discovers and registers them.\n- **Batch**: Use `batch_call` with an array of `{ \"func\", \"args\" }` for better performance.\n\n### 7. Extended scenarios\n\nThe doc in [README.zh-CN.md](README.zh-CN.md) describes extended scenarios (AI texture generation, Poly Haven batch download, project architecture diagrams, performance analysis, test data generation, localization). Use `python_runner` and `code_runner` for automation.\n\n---\n\n## Agent Skills Module\n\nThe MCP protocol exposes full tool lists and parameter schemas to the AI, which can **consume many tokens**. The project adds a **Skill** module (`demo/.cursor/skills`) used together with MCP: load skill docs on demand instead of all tool schemas at once.\n\n### How it works\n\n- **Skill as document**: Each skill is a `SKILL.md` (name, description, parameters, examples).\n- **1:1 with MCP**: Skills describe how to call a tool via MCP (e.g. `async_call` / `batch_call` + `func` and `args`), without re-implementing logic.\n- **On-demand load**: The agent reads only the relevant SKILL file when needed, instead of loading every tool schema.\n\n### With MCP\n\n- **MCP** handles tool discovery and execution; **Skills** describe when and how to pass arguments.\n- Reference skill paths in Cursor Rules or Agent config so the agent consults the right SKILL and then calls MCP.\n- This keeps full MCP capability while **reducing tokens** by not keeping 40+ tool descriptions in context.\n\n### Recommendation\n\nSkills live under `demo/.cursor/skills` (e.g. `unity-async-call`, `unity-hierarchy-create`). No need to list every skill in docs; document that “load the right SKILL.md from `.cursor/skills` on demand” so the agent can use skills and MCP together with less context.\n\n---\n\n## Innovation\n\n### 1. Two-tier call architecture\n- FacadeTools (`async_call`, `batch_call`) + 40+ MethodTools invoked only through them.\n\n### 2. State-tree execution engine\n- State-based routing, parameter validation, unified error handling.\n\n### 3. Message-queue execution\n- Configurable port (default 8000), main-thread safety, EditorApplication.update–based queue.\n\n### 4. Coroutine support\n- Async operations (e.g. HTTP, downloads) without blocking the main thread.\n\n### 5. Smart file/data handling\n- Detect file types; for large content return metadata instead of full data to save memory and bandwidth.\n\n---\n\n## Technical Features\n\n- **Communication**: HTTP, JSON-RPC 2.0, message queue, batch calls  \n- **Reliability**: Configurable port, main-thread safety, error handling, timeouts  \n- **Extensibility**: Modular tools, reflection, custom tools, configurable parameters  \n- **DX**: Natural language, real-time feedback, logging, documentation  \n\n---\n\n## API Reference\n\n### Facade tools\n\n**async_call** — single call:\n```json\n{\n  \"func\": \"async_call\",\n  \"args\": {\n    \"func\": \"hierarchy_create\",\n    \"args\": { \"name\": \"Player\", \"primitive_type\": \"Cube\", \"source\": \"primitive\" }\n  }\n}\n```\n\n**batch_call** — batch:\n```json\n{\n  \"func\": \"batch_call\",\n  \"args\": [\n    { \"func\": \"hierarchy_create\", \"args\": { \"name\": \"Player\", \"primitive_type\": \"Cube\" } },\n    { \"func\": \"edit_gameobject\", \"args\": { \"path\": \"Player\", \"position\": [0, 1, 0] } }\n  ]\n}\n```\n\n### Core tools (examples)\n\n- Hierarchy: hierarchy_create, hierarchy_search, hierarchy_apply  \n- ResEdit: edit_gameobject, edit_component, edit_material, edit_texture  \n- Project: project_search, project_operate  \n- Network: request_http, figma_manage  \n\n### Response format\n\nSuccess: `{ \"success\": true, \"message\": \"...\", \"data\": { ... } }`  \nError: `{ \"success\": false, \"message\": \"...\", \"error\": \"...\" }`\n\n---\n\n## Troubleshooting\n\n### Connection\n\n- **Cannot connect**: Ensure Unity is running, port 8000 (or your port) is free, firewall allows it; check Unity console.\n- **Disconnects**: Check network, Unity performance, and timeout settings.\n\n### Tool execution\n\n- **Call fails**: Check parameter format and types, ensure target objects exist, permissions.\n- **Partial batch failure**: Reorder operations, check resource conflicts, try smaller batches.\n\n### Performance\n\n- **Slow response**: Improve network, reduce Unity load, simplify operations.\n- **High memory**: Destroy unused objects, release resources, check coroutine lifecycle.\n\n### Debugging\n\n- Enable detailed logs (e.g. `McpLogger` in Unity).\n- Use MCP Debug Window for history and re-run.\n- Use network tools (e.g. Wireshark) if needed for HTTP.\n\n---\n\n## Summary\n\nUnity3d MCP connects AI assistants to the Unity Editor via a built-in MCP server, using a two-tier call architecture, message-queue execution, and main-thread safety. It provides 40+ tools across the Unity development pipeline.\n\n### Advantages\n1. **AI-driven**: Natural language control of the Editor  \n2. **Rich**: 40+ tools for the full pipeline  \n3. **Performant**: HTTP + message queue  \n4. **Extensible**: Modular, custom tools  \n5. **Compatible**: Works with major AI clients  \n6. **Zero config**: No external MCP process  \n\n### Use cases\n- AI-assisted game development  \n- Automated resource and batch operations  \n- Education and training  \n\n### Roadmap\n- More Unity tools, visual tool authoring, performance and monitoring, multi-platform support, better debugging.\n\n---\n\n*Document version: v2.0*  \n*Last updated: September 2025*  \n*Unity3d MCP Development Team*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoucdr%2Funity3d-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoucdr%2Funity3d-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoucdr%2Funity3d-mcp/lists"}