{"id":26590139,"url":"https://github.com/codergamester/mcp-unity","last_synced_at":"2025-04-09T18:16:09.240Z","repository":{"id":282323219,"uuid":"948148972","full_name":"CoderGamester/mcp-unity","owner":"CoderGamester","description":"MCP Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor)","archived":false,"fork":false,"pushed_at":"2025-04-05T00:03:58.000Z","size":7598,"stargazers_count":319,"open_issues_count":2,"forks_count":38,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-09T18:16:01.134Z","etag":null,"topics":["claude","copilot","cursor","mcp","mcp-server","typescript","unity","unity-package","windsurf"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CoderGamester.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2025-03-13T20:41:25.000Z","updated_at":"2025-04-09T18:07:52.000Z","dependencies_parsed_at":"2025-03-29T19:37:46.306Z","dependency_job_id":null,"html_url":"https://github.com/CoderGamester/mcp-unity","commit_stats":null,"previous_names":["codergamester/mcp-unity"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoderGamester%2Fmcp-unity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoderGamester%2Fmcp-unity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoderGamester%2Fmcp-unity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoderGamester%2Fmcp-unity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CoderGamester","download_url":"https://codeload.github.com/CoderGamester/mcp-unity/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085322,"owners_count":21045139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["claude","copilot","cursor","mcp","mcp-server","typescript","unity","unity-package","windsurf"],"created_at":"2025-03-23T13:21:11.649Z","updated_at":"2025-04-09T18:16:09.233Z","avatar_url":"https://github.com/CoderGamester.png","language":"C#","readme":"# MCP Unity Editor (Game Engine)\n\n[![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction)\n[![](https://img.shields.io/badge/Unity-000000?style=flat\u0026logo=unity\u0026logoColor=white 'Unity')](https://unity.com/releases/editor/archive)\n[![](https://img.shields.io/badge/Node.js-339933?style=flat\u0026logo=nodedotjs\u0026logoColor=white 'Node.js')](https://nodejs.org/en/download/)\n\n[![smithery badge](https://smithery.ai/badge/@CoderGamester/mcp-unity)](https://smithery.ai/server/@CoderGamester/mcp-unity)\n[![](https://img.shields.io/github/stars/CoderGamester/mcp-unity 'Stars')](https://github.com/CoderGamester/mcp-unity/stargazers)\n[![](https://img.shields.io/github/last-commit/CoderGamester/mcp-unity 'Last Commit')](https://github.com/CoderGamester/mcp-unity/commits/main)\n[![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)\n\n| [English](README.md) | [🇨🇳简体中文](README_zh-CN.md) | [🇯🇵日本語](README-ja.md) |\n|----------------------|---------------------------------|----------------------|\n\n```                                                                        \n                              ,/(/.   *(/,                                  \n                          */(((((/.   *((((((*.                             \n                     .*((((((((((/.   *((((((((((/.                         \n                 ./((((((((((((((/    *((((((((((((((/,                     \n             ,/(((((((((((((/*.           */(((((((((((((/*.                \n            ,%%#((/((((((*                    ,/(((((/(#\u0026@@(                \n            ,%%##%%##((((((/*.             ,/((((/(#\u0026@@@@@@(                \n            ,%%######%%##((/(((/*.    .*/(((//(%@@@@@@@@@@@(                \n            ,%%####%#(%%#%%##((/((((((((//#\u0026@@@@@@\u0026@@@@@@@@(                \n            ,%%####%(    /#%#%%%##(//(#@@@@@@@%,   #@@@@@@@(                \n            ,%%####%(        *#%###%@@@@@@(        #@@@@@@@(                \n            ,%%####%(           #%#%@@@@,          #@@@@@@@(                \n            ,%%##%%%(           #%#%@@@@,          #@@@@@@@(                \n            ,%%%#*              #%#%@@@@,             *%@@@(                \n            .,      ,/##*.      #%#%@@@@,     ./\u0026@#*      *`                \n                ,/#%#####%%#/,  #%#%@@@@, ,/\u0026@@@@@@@@@\u0026\\.                    \n                 `*#########%%%%###%@@@@@@@@@@@@@@@@@@\u0026*´                   \n                    `*%%###########%@@@@@@@@@@@@@@\u0026*´                        \n                        `*%%%######%@@@@@@@@@@\u0026*´                            \n                            `*#%%##%@@@@@\u0026*´                                 \n                               `*%#%@\u0026*´                                     \n                                                       \n     ███╗   ███╗ ██████╗██████╗         ██╗   ██╗███╗   ██╗██╗████████╗██╗   ██╗\n     ████╗ ████║██╔════╝██╔══██╗        ██║   ██║████╗  ██║██║╚══██╔══╝╚██╗ ██╔╝\n     ██╔████╔██║██║     ██████╔╝        ██║   ██║██╔██╗ ██║██║   ██║    ╚████╔╝ \n     ██║╚██╔╝██║██║     ██╔═══╝         ██║   ██║██║╚██╗██║██║   ██║     ╚██╔╝  \n     ██║ ╚═╝ ██║╚██████╗██║             ╚██████╔╝██║ ╚████║██║   ██║      ██║   \n     ╚═╝     ╚═╝ ╚═════╝╚═╝              ╚═════╝ ╚═╝  ╚═══╝╚═╝   ╚═╝      ╚═╝   \n```       \n\nMCP Unity is an implementation of the Model Context Protocol for Unity Editor, allowing AI assistants to interact with your Unity projects. This package provides a bridge between Unity and a Node.js server that implements the MCP protocol, enabling AI agents like Claude, Windsurf, and Cursor to execute operations within the Unity Editor.\n\n## Features\n\n\u003ca href=\"https://glama.ai/mcp/servers/@CoderGamester/mcp-unity\"\u003e\n  \u003cimg width=\"400\" height=\"200\" src=\"https://glama.ai/mcp/servers/@CoderGamester/mcp-unity/badge\" alt=\"Unity MCP server\" /\u003e\n\u003c/a\u003e\n\n### IDE Integration - Package Cache Access\n\nMCP Unity provides automatic integration with VSCode-like IDEs (Visual Studio Code, Cursor, Windsurf) by adding the Unity `Library/PackedCache` folder to your workspace. This feature:\n\n- Improves code intelligence for Unity packages\n- Enables better autocompletion and type information for Unity packages\n- Helps AI coding assistants understand your project's dependencies\n\n### MCP Server Tools\n\n- `execute_menu_item`: Executes Unity menu items (functions tagged with the MenuItem attribute)\n  \u003e **Example prompt:** \"Execute the menu item 'GameObject/Create Empty' to create a new empty GameObject\"\n\n- `select_gameobject`: Selects game objects in the Unity hierarchy by path or instance ID\n  \u003e **Example prompt:** \"Select the Main Camera object in my scene\"\n\n- `update_component`: Updates component fields on a GameObject or adds it to the GameObject if it does not contain the component\n  \u003e **Example prompt:** \"Add a Rigidbody component to the Player object and set its mass to 5\"\n\n- `add_package`: Installs new packages in the Unity Package Manager\n  \u003e **Example prompt:** \"Add the TextMeshPro package to my project\"\n\n- `run_tests`: Runs tests using the Unity Test Runner\n  \u003e **Example prompt:** \"Run all the EditMode tests in my project\"\n\n- `notify_message`: Displays messages in the Unity Editor\n  \u003e **Example prompt:** \"Send a notification to Unity that the task has been completed\"\n\n- `add_asset_to_scene`: Adds an asset from the AssetDatabase to the Unity scene\n  \u003e **Example prompt:** \"Add the Player prefab from my project to the current scene\"\n\n### MCP Server Resources\n\n- `unity://menu-items`: Retrieves a list of all available menu items in the Unity Editor to facilitate `execute_menu_item` tool\n  \u003e **Example prompt:** \"Show me all available menu items related to GameObject creation\"\n\n- `unity://hierarchy`: Retrieves a list of all game objects in the Unity hierarchy\n  \u003e **Example prompt:** \"Show me the current scene hierarchy structure\"\n\n- `unity://gameobject/{id}`: Retrieves detailed information about a specific GameObject by instance ID or object path in the scene hierarchy, including all GameObject components with it's serialized properties and fields\n  \u003e **Example prompt:** \"Get me detailed information about the Player GameObject\"\n\n- `unity://logs`: Retrieves a list of all logs from the Unity console\n  \u003e **Example prompt:** \"Show me the recent error messages from the Unity console\"\n\n- `unity://packages`: Retrieves information about installed and available packages from the Unity Package Manager\n  \u003e **Example prompt:** \"List all the packages currently installed in my Unity project\"\n\n- `unity://assets`: Retrieves information about assets in the Unity Asset Database\n  \u003e **Example prompt:** \"Find all texture assets in my project\"\n\n- `unity://tests/{testMode}`: Retrieves information about tests in the Unity Test Runner\n  \u003e **Example prompt:** \"List all available tests in my Unity project\"\n\n## Requirements\n- Unity 2022.3 or later - to [install the server](#install-server)\n- Node.js 18 or later - to [start the server](#start-server)\n- npm 9 or later - to [debug the server](#debug-server)\n\n## \u003ca name=\"install-server\"\u003e\u003c/a\u003eInstallation\n\nInstalling this MCP Unity Server is a multi-step process:\n\n### Step 1: Install Unity MCP Server package via Unity Package Manager\n1. Open the Unity Package Manager (Window \u003e Package Manager)\n2. Click the \"+\" button in the top-left corner\n3. Select \"Add package from git URL...\"\n4. Enter: `https://github.com/CoderGamester/mcp-unity.git`\n5. Click \"Add\"\n\n![package manager](https://github.com/user-attachments/assets/a72bfca4-ae52-48e7-a876-e99c701b0497)\n\n\n### Step 2: Install Node.js \n\u003e To run MCP Unity server, you'll need to have Node.js 18 or later installed on your computer:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eWindows\u003c/span\u003e\u003c/summary\u003e\n\n1. Visit the [Node.js download page](https://nodejs.org/en/download/)\n2. Download the Windows Installer (.msi) for the LTS version (recommended)\n3. Run the installer and follow the installation wizard\n4. Verify the installation by opening PowerShell and running:\n   ```bash\n   node --version\n   ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003emacOS\u003c/span\u003e\u003c/summary\u003e\n\n1. Visit the [Node.js download page](https://nodejs.org/en/download/)\n2. Download the macOS Installer (.pkg) for the LTS version (recommended)\n3. Run the installer and follow the installation wizard\n4. Alternatively, if you have Homebrew installed, you can run:\n   ```bash\n   brew install node@18\n   ```\n5. Verify the installation by opening Terminal and running:\n   ```bash\n   node --version\n   ```\n\u003c/details\u003e\n\n### Step 3: Configure AI LLM Client\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eOption 1: Configure using Unity Editor\u003c/span\u003e\u003c/summary\u003e\n\n1. Open the Unity Editor\n2. Navigate to Tools \u003e MCP Unity \u003e Server Window\n3. Click on the \"Configure\" button for your AI LLM client as shown in the image below\n\n![image](https://github.com/user-attachments/assets/8d286e83-da60-40fa-bd6c-5de9a77c1820)\n\n4. Confirm the configuration installation with the given popup\n\n![image](https://github.com/user-attachments/assets/b1f05d33-3694-4256-a57b-8556005021ba)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eOption 2: Configure via Smithery\u003c/span\u003e\u003c/summary\u003e\n\nTo install MCP Unity via [Smithery](https://smithery.ai/server/@CoderGamester/mcp-unity):\n\n```\nCurrently not available\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eOption 3: Configure Manually\u003c/span\u003e\u003c/summary\u003e\n\nOpen the MCP configuration file of your AI client (e.g. claude_desktop_config.json in Claude Desktop) and copy the following text:\n\n\u003e Replace `ABSOLUTE/PATH/TO` with the absolute path to your MCP Unity installation or just copy the text from the Unity Editor MCP Server window (Tools \u003e MCP Unity \u003e Server Window).\n\n```json\n{\n   \"mcpServers\": {\n   \"mcp-unity\": {\n      \"command\": \"node\",\n      \"args\": [\n         \"ABSOLUTE/PATH/TO/mcp-unity/Server/build/index.js\"\n      ],\n      \"env\": {\n         \"UNITY_PORT\": \"8090\"\n      }\n   }\n   }\n}\n```\n\n\u003c/details\u003e\n\n## \u003ca name=\"start-server\"\u003e\u003c/a\u003eStart Unity Editor MCP Server\n1. Open the Unity Editor\n2. Navigate to Tools \u003e MCP Unity \u003e Server Window\n3. Click \"Start Server\" to start the WebSocket server\n4. Open Claude Desktop or your AI Coding IDE (e.g. Cursor IDE, Windsurf IDE, etc.) and start executing Unity tools\n   \n![connect](https://github.com/user-attachments/assets/2e266a8b-8ba3-4902-b585-b220b11ab9a2)\n\n\u003e When the AI client connects to the WebSocket server, it will automatically show in the green box in the window\n\n## Optional: Set WebSocket Port\nBy default, the WebSocket server runs on port 8090. You can change this port in two ways:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eOption 1: Using the Unity Editor\u003c/span\u003e\u003c/summary\u003e\n\n1. Open the Unity Editor\n2. Navigate to Tools \u003e MCP Unity \u003e Server Window\n3. Change the \"WebSocket Port\" value to your desired port number\n4. Unity will setup the system environment variable UNITY_PORT to the new port number\n5. Restart the Node.js server\n6. Click again on \"Start Server\" to reconnect the Unity Editor web socket to the Node.js MCP Server\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eOption 2: Using the terminal\u003c/span\u003e\u003c/summary\u003e\n\n1. Set the UNITY_PORT environment variable in the terminal\n   - Powershell\n   ```powershell\n   $env:UNITY_PORT = \"8090\"\n   ```\n   - Command Prompt/Terminal\n   ```cmd\n   set UNITY_PORT=8090\n   ```\n2. Restart the Node.js server\n3. Click again on \"Start Server\" to reconnect the Unity Editor web socket to the Node.js MCP Server\n\n\u003c/details\u003e\n\n## \u003ca name=\"debug-server\"\u003e\u003c/a\u003eDebugging the Server\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eBuilding the Node.js Server\u003c/span\u003e\u003c/summary\u003e\n\nThe MCP Unity server is built using Node.js . It requires to compile the TypeScript code to JavaScript in the `build` directory.\nTo build the server, open a terminal and:\n\n1. Navigate to the Server directory:\n   ```bash\n   cd ABSOLUTE/PATH/TO/mcp-unity/Server\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Build the server:\n   ```bash\n   npm run build\n   ```\n\n4. Run the server:\n   ```bash\n   node build/index.js\n   ```\n\n\u003c/details\u003e\n   \n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eDebugging with MCP Inspector\u003c/span\u003e\u003c/summary\u003e\n\nDebug the server with [@modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector):\n   - Powershell\n   ```powershell\n   $env:UNITY_PORT=8090; npx @modelcontextprotocol/inspector node Server/build/index.js\n   ```\n   - Command Prompt/Terminal\n   ```cmd\n   set UNITY_PORT=8090 \u0026\u0026 npx @modelcontextprotocol/inspector node Server/build/index.js\n   ```\n\nDon't forget to shutdown the server with `Ctrl + C` before closing the terminal or debugging it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eEnable Console Logs\u003c/span\u003e\u003c/summary\u003e\n\n1. Enable logging on your terminal or into a log.txt file:\n   - Powershell\n   ```powershell\n   $env:LOGGING = \"true\"\n   $env:LOGGING_FILE = \"true\"\n   ```\n   - Command Prompt/Terminal\n   ```cmd\n   set LOGGING=true\n   set LOGGING_FILE=true\n   ```\n\n\u003c/details\u003e\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eConnection Issues\u003c/span\u003e\u003c/summary\u003e\n\n- Ensure the WebSocket server is running (check the Server Window in Unity)\n- Check if there are any firewall restrictions blocking the connection\n- Make sure the port number is correct (default is 8080)\n- Change the port number in the Unity Editor MCP Server window. (Tools \u003e MCP Unity \u003e Server Window)\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eServer Not Starting\u003c/span\u003e\u003c/summary\u003e\n\n- Check the Unity Console for error messages\n- Ensure Node.js is properly installed and accessible in your PATH\n- Verify that all dependencies are installed in the Server directory\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cspan style=\"font-size: 1.1em; font-weight: bold;\"\u003eMenu Items Not Executing\u003c/span\u003e\u003c/summary\u003e\n\n- Ensure the menu item path is correct (case-sensitive)\n- Check if the menu item requires confirmation\n- Verify that the menu item is available in the current context\n\u003c/details\u003e\n\n## Support \u0026 Feedback\n\nIf you have any questions or need support, please open an [issue](https://github.com/CoderGamester/mcp-unity/issues) on this repository.\n\nAlternative you can reach out on:\n- Linkedin: [![](https://img.shields.io/badge/LinkedIn-0077B5?style=flat\u0026logo=linkedin\u0026logoColor=white 'LinkedIn')](https://www.linkedin.com/in/miguel-tomas/)\n- Discord: gamester7178\n- Email: game.gamester@gmail.com\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request or open an Issue with your request.\n\n**Commit your changes** following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.\n\n## License\n\nThis project is under [MIT License](License.md)\n\n## Acknowledgements\n\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [Unity Technologies](https://unity.com)\n- [Node.js](https://nodejs.org)\n- [WebSocket-Sharp](https://github.com/sta/websocket-sharp)\n","funding_links":[],"categories":["Browser-extensions"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodergamester%2Fmcp-unity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodergamester%2Fmcp-unity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodergamester%2Fmcp-unity/lists"}