mcp-unity
534
MCP Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor)
Frequently Asked Questions\n\n\nWhat is MCP Unity?
\n\nMCP Unity is a powerful bridge that connects your Unity Editor environment to AI assistants LLM tools using the Model Context Protocol (MCP).\n\nIn essence, MCP Unity:\n- Exposes Unity Editor functionalities (like creating objects, modifying components, running tests, etc.) as "tools" and "resources" that an AI can understand and use.\n- Runs a WebSocket server inside Unity and a Node.js server (acting as a WebSocket client to Unity) that implements the MCP. This allows AI assistants to send commands to Unity and receive information back.\n- Enables you to use natural language prompts with your AI assistant to perform complex tasks within your Unity project, significantly speeding up development workflows.\n\n\n\n\nWhy use MCP Unity?
\n\nMCP Unity offers several compelling advantages for developers, artists, and project managers:\n\n- Accelerated Development: Automate repetitive tasks, generate boilerplate code, and manage assets using AI prompts. This frees up your time to focus on creative and complex problem-solving.\n- Enhanced Productivity: Interact with Unity Editor features without needing to manually click through menus or write scripts for simple operations. Your AI assistant becomes a direct extension of your capabilities within Unity.\n- Improved Accessibility: Allows users who are less familiar with the deep intricacies of the Unity Editor or C# scripting to still make meaningful contributions and modifications to a project through AI guidance.\n- Seamless Integration: Designed to work with various AI assistants and IDEs that support MCP, providing a consistent way to leverage AI across your development toolkit.\n- Extensibility: The protocol and the toolset can be expanded. You can define new tools and resources to expose more of your project-specific or Unity's functionality to AI.\n- Collaborative Potential: Facilitates a new way of collaborating where AI can assist in tasks traditionally done by team members, or help in onboarding new developers by guiding them through project structures and operations.\n\n\n\n\nHow does MCP Unity compare with the upcoming Unity 6.2 AI features?
\n\nUnity 6.2 is set to introduce new built-in AI tools, including the previous Unity Muse (for generative AI capabilities like texture and animation generation) and Unity Sentis (for running neural networks in Unity runtime). As Unity 6.2 is not yet fully released, this comparison is based on publicly available information and anticipated functionalities:\n\n- Focus:\n - MCP Unity: Primarily focuses on Editor automation and interaction. It allows external AI (like LLM-based coding assistants) to control and query the Unity Editor itself to manipulate scenes, assets, and project settings. It's about augmenting the developer's workflow within the Editor.\n - Unity 6.2 AI:\n - Aims at in-Editor content creation (generating textures, sprites, animations, behaviors, scripts) and AI-powered assistance for common tasks, directly integrated into the Unity Editor interface.\n - A fine-tuned model to ask any question about Unity's documentation and API structure, with customized examples more accurate to Unity's environment.\n - Adds the functionality to run AI model inference, allowing developers to deploy and run pre-trained neural networks within your game or application for features like NPC behavior, image recognition, etc.\n\n- Use Cases:\n - MCP Unity: "Create a new 3D object, name it 'Player', add a Rigidbody, and set its mass to 10." "Run all Play Mode tests." "Ask to fix the error on the console log." "Execute the custom menu item 'Prepare build for iOS' and fix any errors that may occur."\n - Unity 6.2 AI: "Generate a sci-fi texture for this material." "Update all trees position in the scene to be placed inside of terrain zones tagged with 'forest'." "Create a walking animation for this character." "Generate 2D sprites to complete the character." "Ask details about the error on the console log."\n\n- Complementary, Not Mutually Exclusive:\n MCP Unity and Unity's native AI tools can be seen as complementary. You might use MCP Unity with your AI coding assistant to set up a scene or batch-modify assets, and then use Unity AI tools to generate a specific texture, or to create animations, or 2D sprites for one of those assets. MCP Unity provides a flexible, protocol-based way to interact with the Editor, which can be powerful for developers who want to integrate with a broader range of external AI services or build custom automation workflows.\n\n\n\n\nWhat MCP hosts and IDEs currently support MCP Unity?
\n\nMCP Unity is designed to work with any AI assistant or development environment that can act as an MCP client. The ecosystem is growing, but current known integrations or compatible platforms include:\n- Windsurf\n- Cursor\n- GitHub Copilot\n- Claude Desktop\n\n\n\n\nCan I extend MCP Unity with custom tools for my project?
\n\nYes, absolutely! One of the significant benefits of the MCP Unity architecture is its extensibility.\n- In Unity (C#): You can create new C# classes that inherit from McpToolBase (or a similar base for resources) to expose custom Unity Editor functionality. These tools would then be registered in McpUnityServer.cs. For example, you could write a tool to automate a specific asset import pipeline unique to your project.\n- In Node.js Server (TypeScript): You would then define the corresponding TypeScript tool handler in the Server/src/tools/ directory, including its Zod schema for inputs/outputs, and register it in Server/src/index.ts. This Node.js part will forward the request to your new C# tool in Unity.\n\nThis allows you to tailor the AI's capabilities to the specific needs and workflows of your game or application.\n\n\n\n\nIs MCP Unity free to use?
\n\nYes, MCP Unity is an open-source project distributed under the MIT License. You are free to use, modify, and distribute it according to the license terms.\n\n\n\n\nWhy am I unable to connect to MCP Unity?
\n\n- Ensure the WebSocket server is running (check the Server Window in Unity)\n- Send a console log message from MCP client to force a reconnection between MCP client and Unity server\n- Change the port number in the Unity Editor MCP Server window. (Tools > MCP Unity > Server Window)\n\n\n\n\nWhy won't the MCP Unity server start?
\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\n\n\n\nWhy do I get a connection failed error when running Play Mode tests?
\n\nThe run_tests tool returns the following response:\n\nError:\nConnection failed: Unknown error\n\n\nThis error occurs because the bridge connection is lost when the domain reloads upon switching to Play Mode. \nThe workaround is to turn off Reload Domain in Edit > Project Settings > Editor > "Enter Play Mode Settings".\n\n
What is MCP Unity?
\n\nMCP Unity is a powerful bridge that connects your Unity Editor environment to AI assistants LLM tools using the Model Context Protocol (MCP).\n\nIn essence, MCP Unity:\n- Exposes Unity Editor functionalities (like creating objects, modifying components, running tests, etc.) as "tools" and "resources" that an AI can understand and use.\n- Runs a WebSocket server inside Unity and a Node.js server (acting as a WebSocket client to Unity) that implements the MCP. This allows AI assistants to send commands to Unity and receive information back.\n- Enables you to use natural language prompts with your AI assistant to perform complex tasks within your Unity project, significantly speeding up development workflows.\n\nWhy use MCP Unity?
\n\nMCP Unity offers several compelling advantages for developers, artists, and project managers:\n\n- Accelerated Development: Automate repetitive tasks, generate boilerplate code, and manage assets using AI prompts. This frees up your time to focus on creative and complex problem-solving.\n- Enhanced Productivity: Interact with Unity Editor features without needing to manually click through menus or write scripts for simple operations. Your AI assistant becomes a direct extension of your capabilities within Unity.\n- Improved Accessibility: Allows users who are less familiar with the deep intricacies of the Unity Editor or C# scripting to still make meaningful contributions and modifications to a project through AI guidance.\n- Seamless Integration: Designed to work with various AI assistants and IDEs that support MCP, providing a consistent way to leverage AI across your development toolkit.\n- Extensibility: The protocol and the toolset can be expanded. You can define new tools and resources to expose more of your project-specific or Unity's functionality to AI.\n- Collaborative Potential: Facilitates a new way of collaborating where AI can assist in tasks traditionally done by team members, or help in onboarding new developers by guiding them through project structures and operations.\n\nHow does MCP Unity compare with the upcoming Unity 6.2 AI features?
\n\nUnity 6.2 is set to introduce new built-in AI tools, including the previous Unity Muse (for generative AI capabilities like texture and animation generation) and Unity Sentis (for running neural networks in Unity runtime). As Unity 6.2 is not yet fully released, this comparison is based on publicly available information and anticipated functionalities:\n\n- Focus:\n - MCP Unity: Primarily focuses on Editor automation and interaction. It allows external AI (like LLM-based coding assistants) to control and query the Unity Editor itself to manipulate scenes, assets, and project settings. It's about augmenting the developer's workflow within the Editor.\n - Unity 6.2 AI:\n - Aims at in-Editor content creation (generating textures, sprites, animations, behaviors, scripts) and AI-powered assistance for common tasks, directly integrated into the Unity Editor interface.\n - A fine-tuned model to ask any question about Unity's documentation and API structure, with customized examples more accurate to Unity's environment.\n - Adds the functionality to run AI model inference, allowing developers to deploy and run pre-trained neural networks within your game or application for features like NPC behavior, image recognition, etc.\n\n- Use Cases:\n - MCP Unity: "Create a new 3D object, name it 'Player', add a Rigidbody, and set its mass to 10." "Run all Play Mode tests." "Ask to fix the error on the console log." "Execute the custom menu item 'Prepare build for iOS' and fix any errors that may occur."\n - Unity 6.2 AI: "Generate a sci-fi texture for this material." "Update all trees position in the scene to be placed inside of terrain zones tagged with 'forest'." "Create a walking animation for this character." "Generate 2D sprites to complete the character." "Ask details about the error on the console log."\n\n- Complementary, Not Mutually Exclusive:\n MCP Unity and Unity's native AI tools can be seen as complementary. You might use MCP Unity with your AI coding assistant to set up a scene or batch-modify assets, and then use Unity AI tools to generate a specific texture, or to create animations, or 2D sprites for one of those assets. MCP Unity provides a flexible, protocol-based way to interact with the Editor, which can be powerful for developers who want to integrate with a broader range of external AI services or build custom automation workflows.\n\nWhat MCP hosts and IDEs currently support MCP Unity?
\n\nMCP Unity is designed to work with any AI assistant or development environment that can act as an MCP client. The ecosystem is growing, but current known integrations or compatible platforms include:\n- Windsurf\n- Cursor\n- GitHub Copilot\n- Claude Desktop\n\nCan I extend MCP Unity with custom tools for my project?
\n\nYes, absolutely! One of the significant benefits of the MCP Unity architecture is its extensibility.\n- In Unity (C#): You can create new C# classes that inherit fromMcpToolBase (or a similar base for resources) to expose custom Unity Editor functionality. These tools would then be registered in McpUnityServer.cs. For example, you could write a tool to automate a specific asset import pipeline unique to your project.\n- In Node.js Server (TypeScript): You would then define the corresponding TypeScript tool handler in the Server/src/tools/ directory, including its Zod schema for inputs/outputs, and register it in Server/src/index.ts. This Node.js part will forward the request to your new C# tool in Unity.\n\nThis allows you to tailor the AI's capabilities to the specific needs and workflows of your game or application.\n\nIs MCP Unity free to use?
\n\nYes, MCP Unity is an open-source project distributed under the MIT License. You are free to use, modify, and distribute it according to the license terms.\n\nWhy am I unable to connect to MCP Unity?
\n\n- Ensure the WebSocket server is running (check the Server Window in Unity)\n- Send a console log message from MCP client to force a reconnection between MCP client and Unity server\n- Change the port number in the Unity Editor MCP Server window. (Tools > MCP Unity > Server Window)\n\nWhy won't the MCP Unity server start?
\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\nWhy do I get a connection failed error when running Play Mode tests?
\n\nTherun_tests tool returns the following response:\n\nError:\nConnection failed: Unknown error\n\n\nThis error occurs because the bridge connection is lost when the domain reloads upon switching to Play Mode. \nThe workaround is to turn off Reload Domain in Edit > Project Settings > Editor > "Enter Play Mode Settings".\n\n