session-setup

Blender Remote Session Setup

First-Time Setup

Install Python dependencies (only needed once, or after plugin updates):

cd <plugin-dir>
uv sync

uv sync reads pyproject.toml and creates a .venv with blender-remote and openpyxl. This also happens automatically at session start if the plugin's SessionStart hook is active.

Starting a Session

Two terminals are required on the same machine. Both must stay running — if Blender Remote stops, the MCP connection is lost.

Terminal 1 — start Blender headless:

blender-start
# Equivalent long form:
cd <project-dir> && source .venv/bin/activate \
  && fuser -k 6688/tcp 2>/dev/null \
  ; pkill -f blender 2>/dev/null \
  ; sleep 1 \
  && blender-remote-cli start --background --port 6688

Terminal 2 — start Claude Code:

source .venv/bin/activate
claude

Inside Claude Code, verify MCP tools are loaded:

/mcp

blender must appear as an active server before issuing any Blender commands.

Convenience Aliases

If the aliases are not yet set up, add them to ~/.bashrc (replace <project-dir> with the actual path):

alias blender-start='cd <project-dir> && source .venv/bin/activate && fuser -k 6688/tcp 2>/dev/null; pkill -f blender 2>/dev/null; sleep 1 && blender-remote-cli start --background --port 6688'
alias blender-stop='fuser -k 6688/tcp 2>/dev/null; pkill -f blender 2>/dev/null'
alias blender-restart='blender-stop && sleep 1 && blender-start'

Then reload: source ~/.bashrc

Stopping and Restarting

blender-stop      # kill Blender and free port 6688
blender-restart   # stop then start in one command

Project Structure — Scripts and CLAUDE.md

Save generated scripts locally

Every Python script executed via the MCP should also be saved to a local scripts/ folder so it can be inspected, reused, and version-controlled. Create the folder once:

mkdir -p scripts

Name scripts descriptively, e.g.:

• scripts/import_battery_pack.py
• scripts/setup_studio_lighting.py
• scripts/render_orbit_animation.py

When asked to execute a Blender script, always write it to scripts/<name>.py first, then send it to Blender via the MCP tool.

Maintain a CLAUDE.md

Create or update a CLAUDE.md in the project root to document project-specific paths and settings. Claude Code reads this file at session start, so it is the right place for persistent context.

Minimal template — adapt paths to your setup:

# Blender Remote — Project Context

## Environment
- Blender port: 6688
- Project dir: /path/to/project
- Scripts dir: /path/to/project/scripts
- Data dir: /path/to/project/data

## Data Files
- CAD assembly: data/<filename>.stp  (convert to GLTF before import)
- BOM spreadsheet: data/<filename>.xlsx

## Custom Settings
- Render output: /tmp/renders/
- Default resolution: 1920x1080
- Default samples: 128

Update CLAUDE.md whenever new data files are added or project paths change.

Troubleshooting

Port already in use

fuser -k 6688/tcp
# or identify the process first:
ss -tulpn | grep 6688
kill <PID>

CUDA not detected

Check that NVIDIA drivers are working:

nvidia-smi

Verify Blender detects the GPU:

blender --background --python-expr "
import bpy
cprefs = bpy.context.preferences.addons['cycles'].preferences
cprefs.get_devices()
for d in cprefs.devices:
    print(d.name, d.type, d.use)
"

CUDA is enabled persistently via a startup script at: ~/.config/blender/<version>/scripts/startup/enable_cuda.py

If the file is missing, recreate it:

BLENDER_VERSION=$(blender --version | head -1 | awk '{print $2}' | cut -d. -f1,2)
mkdir -p ~/.config/blender/$BLENDER_VERSION/scripts/startup

cat > ~/.config/blender/$BLENDER_VERSION/scripts/startup/enable_cuda.py << 'EOF'
import bpy

def enable_cuda():
    try:
        cprefs = bpy.context.preferences.addons['cycles'].preferences
        cprefs.compute_device_type = 'CUDA'
        cprefs.get_devices()
        for device in cprefs.devices:
            device.use = (device.type == 'CUDA')
        bpy.context.scene.cycles.device = 'GPU'
        bpy.context.scene.render.engine = 'CYCLES'
        bpy.ops.wm.save_userpref()
        print("CUDA enabled:", [d.name for d in cprefs.devices if d.use])
    except Exception as e:
        print(f"CUDA setup failed: {e}")

import bpy.app.timers
bpy.app.timers.register(enable_cuda, first_interval=1.0)
EOF

requests module missing (addon install error)

Run in Blender's Python console (Scripting workspace):

import subprocess, sys
subprocess.call([sys.executable, '-m', 'pip', 'install', 'requests'])

blender-remote-cli init fails (no auto-detect)

blender-remote-cli init --blender-path $(which blender)

Re-register MCP server

claude mcp remove blender
claude mcp add blender \
  -e BLENDER_HOST=localhost \
  -e BLENDER_PORT=6688 \
  -- uvx blender-remote --host localhost --port 6688
claude mcp list