Unity MCP Integration
This package provides a seamless integration between Model Context Protocol (MCP) and Unity Editor, allowing AI assistants to understand and interact with your Unity projects in real-time. With this integration, AI assistants can access information about your scene hierarchy, project settings, and execute code directly in the Unity Editor context.
📚 What is MCP?
The Model Context Protocol (MCP) is a standardized protocol that connects AI models to tools and context sources. It enables AI assistants to:
- Access real-time information about your Unity project
- Understand your scene hierarchy and game objects
- Execute C# code directly in the Unity Editor
- Monitor logs and errors
- Control the Editor's play mode
🚀 Getting Started
Prerequisites
- Unity 2021.3 or later
- Node.js 18+ (for running the MCP server)
Installation
1. Install Unity Package
You have several options to install the Unity package:
Option A: Package Manager (Git URL)
- Open the Unity Package Manager (
Window > Package Manager)
- Click the
+ button and select Add package from git URL...
- Enter the repository URL:
https://github.com/shahzadgamedev/UnityMCPIntegration.git
- Click
Add
Option B: Import Custom Package
- Clone this repository or download it as a zip
- In Unity, go to
Assets > Import Package > Custom Package
- Select the
UnityMCPIntegration.unitypackage file
2. Set up the MCP Server
You have two options to run the MCP server:
Option A: Run the server directly
Navigate to the mcpServer directory
Install dependencies:
npm install
Run the server:
node build/index.js
Option B: Add to MCP Host configuration
Add the server to your MCP Host configuration for Claude Desktop, Custom Implementation etc
{
"mcpServers": {
"unity-mcp-server": {
"command": "node",
"args": [
"<path-to-project>/mcpServer/build/index.js"
]
}
}
}
🔧 Usage
Debugging and Monitoring
You can open the MCP Debug window in Unity to monitor the connection and test features:
- Go to
Window > MCP Debug
- Use the debug window to:
* Check connection status
* Test code execution
* View logs
* Monitor events
Available Tools
The Unity MCP integration provides several tools to AI assistants:
- get_editor_state : Get comprehensive information about the Unity project and editor state
- get_current_scene_info : Get detailed information about the current scene
- get_game_objects_info : Get information about specific GameObjects in the scene
- execute_editor_command : Execute C# code directly in the Unity Editor
- get_logs : Retrieve and filter Unity console logs
🛠️ Architecture
The integration consists of two main components:
- Unity Plugin (C#) : Resides in the Unity Editor and provides access to Editor APIs
- MCP Server (TypeScript/Node.js) : Implements the MCP protocol and communicates with the Unity plugin
Communication between them happens via WebSocket, transferring JSON messages for commands and data.
👥 Contributing
Contributions are welcome! Here's how you can contribute:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Make your changes
- Commit your changes (
git commit -m 'Add some amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Development Setup
Unity Side :
- Open the project in Unity
- Modify the C# scripts in the
UnityMCPConnection/Editor directory
Server Side :
- Navigate to the
mcpServer directory
- Install dependencies:
npm install
- Make changes to the TypeScript files in the
src directory
- Build the server:
npm run build
- Run the server:
node build/index.js
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
📞 Support
If you encounter any issues or have questions, please file an issue on the GitHub repository.
