Hunyuan3D v2 and Blender MCP Setup Guide

Hunyuan3D-2 combined with Blender MCP lets Claude Desktop generate, texture, and place 3D assets inside Blender via natural language — no manual export/import steps required. This guide covers the full local setup: Blender and Claude on Windows, and the GPU-intensive Hunyuan3D-2 model server in WSL2.

Blender MCP Configuration

The Blender MCP server allows Model Context Protocol clients (like Claude Desktop) to invoke commands, query objects, and execute Python scripts directly inside an active Blender instance.

Installing the Blender Addon

To start, download the addon.py file from the official blender-mcp GitHub repository.

Install it into Blender following these standard steps:

1. Open Blender.
2. Navigate to Edit → Preferences → Add-ons.
3. Click the Install... button in the top-right corner.
4. Locate and select the downloaded addon.py file, then click Install Add-on.
5. Locate the System: BlenderMCP add-on in the list and check the box to enable it.

Once installed and enabled:

• Open the 3D Viewport.
• Press N to open the sidebar.
• Click the BlenderMCP tab.
• Click Start MCP Server to run the local RPC listener (defaults to port 9876).

Preparing the Python Environment

To launch the MCP client-server bridge securely, a dedicated Python 3.12 environment is recommended. Running uvx blender-mcp on newer versions of Python (e.g., 3.14) can encounter compile issues with dependencies like pyiceberg.

Set up a dedicated Conda environment using the following terminal commands:

# Create a Python 3.12 Conda environment
conda create -n py312 python=3.12 -y

# Activate the environment
conda activate py312

# Install the uv package manager for faster execution
pip install uv

Configuring Claude Desktop

Claude Desktop needs to be configured to recognize the Blender MCP server. Locate or create your Claude configuration file at: %APPDATA%\Claude\claude_desktop_config.json

Add the following config snippet to register the blender server, making sure to replace the paths to match your actual Anaconda installation:

{
  "mcpServers": {
    "blender": {
      "command": "C:/Users/laxmi/anaconda3/envs/py312/Scripts/uvx.exe",
      "args": [
        "--python",
        "C:/Users/laxmi/anaconda3/envs/py312/python.exe",
        "blender-mcp"
      ]
    }
  }
}

Initialization Order

For the connection to establish correctly, components must be initialized in this specific order:

1. Launch Blender and ensure the MCP Server is running (via the N panel).
2. Start Claude Desktop.
3. Start a fresh conversation in Claude.

Hunyuan3D-2 Setup (WSL2)

Hunyuan3D-2 requires a high-performance NVIDIA GPU with CUDA. For Windows users, running it within WSL2 (Ubuntu) is highly recommended.

Installation

Set up a dedicated Python 3.12 environment in WSL2 and clone the repository:

# Create and activate environment
conda create -n hunyuan3d_312 python=3.12 -y
conda activate hunyuan3d_312

# Install PyTorch with CUDA support (matching PyTorch index URL)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130

# Clone the repository
cd ~
git clone https://github.com/Tencent/Hunyuan3D-2
cd Hunyuan3D-2

# Install main packages
pip install -r requirements.txt
pip install -e .

# Install dependencies for compilation
pip install sentencepiece tiktoken pybind11 ninja "pybind11[global]" huggingface_hub

# Compile differentiable renderer
cd hy3dgen/texgen/differentiable_renderer
pip install -e .
cd ~/Hunyuan3D-2

Downloading Weights

Retrieve the lightweight model weights from Hugging Face:

# Download Hunyuan3D-2 mini model weights using huggingface-cli or huggingface_hub
huggingface-cli download tencent/Hunyuan3D-2mini --local-dir ~/Hunyuan3D-2/weights

Running the API Server

Hunyuan3D-2 exposes a simple server wrapper. Execute this in your WSL2 shell:

# Activate the environment and run the server
conda activate hunyuan3d_312
cd ~/Hunyuan3D-2
python api_server.py --host 0.0.0.0 --port 8081 --model_path ~/Hunyuan3D-2/weights --device cuda

Note: WSL2 automatically forwards local network ports to Windows, meaning localhost:8081 will be accessible directly from Windows without further configuration.

Blender MCP Panel Settings

Back in Blender, adjust the following options in the BlenderMCP N-panel:

VRAM and Performance Scaling

Adjust the Octree Resolution based on your GPU's capacity:

Running the Gradio Web UI (Optional)

If you wish to test generation directly through a web browser instead of the MCP interface:

# Launch Gradio UI without texture mapping support
cd ~/Hunyuan3D-2
python gradio_app.py --model_path ~/Hunyuan3D-2/weights --device cuda --disable_tex --port 8080 --enable_t23d

# Launch Gradio UI with texture mapping (requires Part 3 weights)
cd ~/Hunyuan3D-2
LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/torch/lib:$CONDA_PREFIX/lib \
python gradio_app.py --model_path ~/Hunyuan3D-2/weights --texgen_model_path ~/Hunyuan3D-2/weights --device cuda --port 8080 --enable_t23d

Open http://localhost:8080 in your browser. Remember that for the Blender MCP integration, you must keep the api_server.py running on port 8081.

Enabling Texture Generation

To enable realistic texturing and mapping on the generated models, we need to download additional weights and compile the custom rasterizer kernel.

Install System Libraries

Ensure OpenGL support is installed on your WSL2 environment:

sudo apt-get update
sudo apt-get install -y libopengl0

Download Texture Weights

Run the following commands to download the Paint and Delight weights:

# Download Paint Turbo model weights
huggingface-cli download tencent/Hunyuan3D-2 --include "hunyuan3d-paint-v2-0-turbo/*" --local-dir ~/Hunyuan3D-2/weights

# Download Delight model weights (removes highlights/shadows for clean textures)
huggingface-cli download tencent/Hunyuan3D-2 --include "hunyuan3d-delight-v2-0/*" --local-dir ~/Hunyuan3D-2/weights

Compiling the CUDA Custom Rasterizer

To build the CUDA kernels, install the CUDA Toolkit package inside your conda environment:

# Install matching CUDA Toolkit
conda install -c nvidia/label/cuda-13.0.0 cuda-toolkit -y

# Compile custom rasterizer
cd ~/Hunyuan3D-2/hy3dgen/texgen/custom_rasterizer
CUDA_HOME=$CONDA_PREFIX pip install . --no-build-isolation
cd ~/Hunyuan3D-2

Remote Code Execution Patch

The pipeline loader requires an explicit trust_remote_code=True parameter to load local configurations safely. Edit the file hy3dgen/texgen/utils/multiview_utils.py around line 34:

# Before patch
pipeline = DiffusionPipeline.from_pretrained(
    multiview_ckpt_path,
    custom_pipeline=custom_pipeline_path, torch_dtype=torch.float16)

# After patch
pipeline = DiffusionPipeline.from_pretrained(
    multiview_ckpt_path,
    custom_pipeline=custom_pipeline_path, torch_dtype=torch.float16,
    trust_remote_code=True)

Running the Texturing API Server

Run the API server with the --enable_tex flag:

cd ~/Hunyuan3D-2
LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/torch/lib:$CONDA_PREFIX/lib \
python api_server.py \
  --host 0.0.0.0 --port 8081 \
  --model_path ~/Hunyuan3D-2/weights \
  --tex_model_path ~/Hunyuan3D-2/weights/hunyuan3d-paint-v2-0-turbo \
  --device cuda --enable_tex

Reference

Model Options

Generation Parameters

API Endpoints