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 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:

# 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.

Comparison: Standard vs Extended

Choose the standard server for basic functionality or the extended server for advanced features.

Development

See the Project Document and 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

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 for more details on this planned development.

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

# 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

# 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:
   Copy

   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

# Make sure your virtual environment is activated
python main.py

Option B: Extended Server (More features)

# 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:

{
    "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 and workflow directory.

License

This project is licensed under the MIT License - see the LICENSE file for details.