UnrealBlender

You run a unified MCP server that lets AI agents control both Blender and Unreal Engine through a single interface. This enables coordinated tasks like creating objects in Blender while simultaneously configuring levels in Unreal, all via natural prompts or scripted commands.

How to use

Use an MCP client to connect to the central server. The server exposes an SSE-based feed for AI agents and routes commands to the Blender addon and the Unreal Engine plugin. You can start with the standard server for basic control, then switch to the extended server for additional features. Once running, ask your AI agent to perform combined tasks such as modelling in Blender and level setup in Unreal within the same workflow.

How to install

Prerequisites include a Python 3.10+ environment, Blender 3.0+, Unreal Engine 5.0+, and uv for Python package management.

1. Clone the repository with submodules or clone and initialize submodules later.

# Clone with submodules (recommended)
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp

# Or clone normally and initialize submodules
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

2. Set up a Python environment and install dependencies.

# 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 the Blender addon or extended addon.

# Option A: Standard Addon (Original blender-mcp)
1. Open Blender
2. Edit > Preferences > Add-ons
3. Click "Install..." and select `blender-mcp/addon.py`
4. Enable the "Interface: Blender MCP" addon

# Option B: Extended Addon (With additional features)
python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"
3. Open Blender
4. Edit > Preferences > Add-ons
5. Enable the "Interface: Extended Blender MCP" addon

4. Install the 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. Edit > Plugins in the menu
5. Enable the Python Server plugin
6. Restart Unreal Engine when prompted

5. Start the MCP server.

# Standard Server
python main.py

# Extended Server (More features)
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 in Blender.

- Start Blender
- In the 3D viewport, press N to open the sidebar
- Select the appropriate tab: "BlenderMCP" or "ExtBlenderMCP"
- Click "Start Server"
- Verify the server starts successfully in the console output

7. Verify Unreal Engine connection.

- Ensure Unreal Engine is running with the plugin enabled
- The Python server should start automatically
- Open Window > Developer Tools > Output Log to view messages
- The Unreal plugin is ready to receive commands

8. Connect an AI agent.

Standard agent setup (example) involves pointing the agent to the MCP server URL and configuring it to launch the appropriate server command. You can use a local agent integration to run the standard or extended MCP server commands directly.

Additional notes

The system is designed with an extension structure to maintain compatibility with upstream changes. The Blender addon and the server are extended in a way that keeps the original code intact while adding Unreal Engine integration and new tools.

Troubleshooting tips include ensuring all servers are running, checking port configurations, and restarting components in the correct order: MCP server first, then Blender, then Unreal Engine.

Available tools

mcp_server

Central hub that communicates with AI agents via SSE on port 8000 and routes commands to Blender addon and Unreal plugin.

blender_addon

Blender addon exposing MCP server functionality on port 8400/8401 to accept and execute MCP commands in the Blender scene.

unreal_plugin

Unreal Engine plugin exposing a Python server on port 8500 to receive MCP commands and control Unreal Engine tasks.