Ureanl-Blender-MCP

# Unreal-Blender MCP Unreal-Blender MCP is a unified server for controlling both Blender and Unreal Engine via AI agents using the MCP (Machine Control Protocol) approach. ## Overview This project extends the [blender-mcp](https://github.com/ahujasid/blender-mcp.git) framework to include support for Unreal Engine, allowing AI agents like Claude and ChatGPT to simultaneously control both platforms through a single interface. ## Submodule Information This project includes `blender-mcp` as a Git submodule. When cloning the repository, use the following commands: ```bash # Clone with submodules git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git # Or clone normally and then initialize submodules git clone https://github.com/tahooki/unreal-blender-mcp.git cd unreal-blender-mcp git submodule update --init --recursive ``` ## Features - **Unified Control**: Single MCP server to control both Blender and Unreal Engine - **AI Agent Integration**: Designed to work with Claude, ChatGPT, and other AI assistants - **Blender Features**: Retains all blender-mcp functionality including: - Scene manipulation - Object creation and editing - Material management - PolyHaven asset integration - Hyper3D Rodin model generation - **Unreal Engine Features**: - Level creation and management - Asset importing - Python code execution - Scene manipulation - **Extension Structure**: Easily extend both Blender addon and server while maintaining compatibility with upstream updates ## Architecture The system consists of three main components: 1. **MCP Server**: Central hub communicating with AI agents via SSE (Server-Sent Events) on port 8000 2. **Blender Addon**: Socket server within Blender on port 8400 (standard) or 8401 (extended) 3. **Unreal Plugin**: HTTP server within Unreal Engine on port 8500 ``` [AI Agent] <--SSE--> [MCP Server (8300)] | |--HTTP--> [Blender Addon (8400)] | |--HTTP--> [Unreal Plugin (8500)] ``` ## Extension Structure This project uses an extension approach to maintain compatibility with upstream changes: - **Blender Addon Extension**: Extends the original `BlenderMCPServer` while keeping the original code intact - **Server Extension**: Enhances the original server with additional tools and Unreal Engine integration - **Interface Tools**: Provides utilities for installing, configuring, and running extensions This approach allows easy updates from the original projects without code conflicts. ## Step-by-Step Installation and Setup Guide ### Prerequisites - Python 3.10 or later - Blender 3.0 or later - Unreal Engine 5.0 or later - uv package manager (install with `pip install uv` if you don't have it) ### 1. Clone the Repository ```bash # Clone with submodules (recommended) git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git cd unreal-blender-mcp # Or if you already cloned without --recursive: git clone https://github.com/tahooki/unreal-blender-mcp.git cd unreal-blender-mcp git submodule update --init --recursive ``` ### 2. Set Up Python Environment ```bash # Create a virtual environment and activate it uv venv # On Windows: .\venv\Scripts\activate # On macOS/Linux: source venv/bin/activate # Install project dependencies uv pip install -e . ``` ### 3. Install Blender Addon Choose ONE of the following options: #### Option A: Standard Addon (Original blender-mcp) 1. Open Blender 2. Navigate to Edit > Preferences > Add-ons 3. Click "Install..." button 4. Browse and select `blender-mcp/addon.py` file 5. Enable the "Interface: Blender MCP" addon (check the box) #### Option B: Extended Addon (With additional features) 1. Run the extension installer script: ```bash python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)" ``` 2. Open Blender 3. Navigate to Edit > Preferences > Add-ons 4. Find and enable the "Interface: Extended Blender MCP" addon (check the box) ### 4. Install Unreal Engine Plugin 1. Locate the `UEPythonServer` folder in this project 2. Copy the entire folder to your Unreal project's `Plugins` directory - If your project doesn't have a `Plugins` directory, create one 3. Start Unreal Engine with your project 4. Navigate to Edit > Plugins in the menu 5. Find and enable the Python Server plugin 6. Restart Unreal Engine when prompted ### 5. Start the MCP Server Choose ONE of the following options: #### Option A: Standard Server ```bash # Make sure your virtual environment is activated python main.py ``` #### Option B: Extended Server (More features) ```bash # Make sure your virtual environment is activated python run_extended_server.py # Optional: Customize server options python run_extended_server.py --host 127.0.0.1 --port 8080 --log-level DEBUG ``` ### 6. Enable the Blender Server Connection 1. Start Blender (if not already running) 2. In the 3D viewport, press `N` to open the sidebar panel 3. Select the appropriate tab: - "BlenderMCP" (if using standard addon) - "ExtBlenderMCP" (if using extended addon) 4. Click the "Start Server" button 5. Verify the server starts successfully (check console output) ### 7. Verify Unreal Engine Connection 1. With Unreal Engine running and plugin enabled 2. The Python server should automatically start 3. Check the Output Log (Window > Developer Tools > Output Log) for any messages 4. The Unreal plugin should now be ready to receive commands ### 8. Connect an AI Agent #### Option A: Integrate with Claude for Desktop Add the following to Claude for Desktop's configuration: ```json { "mcpServers": { "unreal-blender": { "command": "uvx", "args": [ "unreal-blender-mcp" ] }, "unreal-blender-ext": { "command": "python", "args": [ "/path/to/unreal-blender-mcp/run_extended_server.py" ] } } } ``` Replace `/path/to/` with your actual project path. #### Option B: Integrate with Cursor 1. Open Cursor Settings 2. Navigate to MCP section 3. Add the following commands: - Standard Server: `uvx unreal-blender-mcp` - Extended Server: `python /path/to/unreal-blender-mcp/run_extended_server.py` Replace `/path/to/` with your actual project path. #### Option C: Integrate with Other AI Tools Refer to your AI tool's documentation for integrating with MCP servers, and point it to: - MCP Server URL: `http://localhost:8000` (or custom port if specified) ### 9. Testing the System Once all components are running: 1. Use your AI agent to interact with Blender by asking it to: - Create a simple cube or sphere - Modify object properties - Create materials 2. Use your AI agent to interact with Unreal Engine by asking it to: - Create a new level - Place assets - Modify scene properties 3. Try more complex operations that involve both platforms working together ### Troubleshooting If you encounter issues: 1. Check that all servers are running (MCP, Blender, Unreal) 2. Verify port configurations match (default: 8000 for MCP, 8400/8401 for Blender, 8500 for Unreal) 3. Check console outputs for error messages 4. Restart components in the correct order: MCP server first, then Blender, then Unreal Engine For more detailed information on development and extending the system, see the [Project Document](Project-document.md) and [workflow](workflow/) directory. ## Comparison: Standard vs Extended | Feature | Standard Server | Extended Server | |---------|----------------|----------------| | Blender Control | ✅ | ✅ | | Unreal Control | ✅ | ✅ | | Custom Blender Commands | ❌ | ✅ | | Enhanced Scene Info | ❌ | ✅ | | Auto Feature Detection | ❌ | ✅ | | Upstream Compatibility | ✅ | ✅ | Choose the standard server for basic functionality or the extended server for advanced features. ## Development See the [Project Document](Project-document.md) and [workflow](workflow/) directory for detailed development information. For extending this project: - To add new Blender addon features: Modify `src/unreal_blender_mcp/blender_addon/extended_addon.py` - To add new server tools: Modify `src/unreal_blender_mcp/server_extension/extended_server.py` ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Acknowledgements - This project builds upon [blender-mcp](https://github.com/ahujasid/blender-mcp.git) by Siddharth Ahuja. ## Future Developments The following improvements are planned for future releases: ### Structured Unreal Engine API Currently, the Unreal Engine communication relies primarily on direct Python code execution. A planned enhancement is to implement a structured API similar to the Blender integration: - Create predefined functions for common Unreal Engine operations - Implement proper error handling and validation - Improve security by limiting execution scope - Enhance stability and predictability of operations - Maintain backward compatibility while adding structure This enhancement will create a more consistent experience across both engines and improve the overall reliability of the system. See the [workflow documentation](workflow/08-unreal-engine-refinement.md) for more details on this planned development.