Getting Started¶

Complete guide to installing BlenderForge and connecting it to your AI assistant.

Table of Contents¶

• System Requirements
• Quick Start
• Step 1: Install BlenderForge
• Step 2: Install the Blender Addon
• Step 3: Configure Your AI Assistant
• Step 4: Connect Everything
• Step 5: Try It Out
• Environment Variables
• Advanced Configuration
• Platform-Specific Notes
• Next Steps

System Requirements¶

Minimum Requirements¶

Software Prerequisites¶

1. Python 3.10+
2. Download Python

3. Verify: python --version or python3 --version

4. Blender 3.0+

5. Download Blender
6. Recommended: Blender 4.x for best compatibility

7. Verify: Open Blender → Help → About Blender

8. MCP-Compatible AI Assistant

9. See AI Clients for supported platforms
10. Popular options: Claude Desktop, VS Code + Copilot, Cursor

Network Requirements¶

• Internet connection required for:
• PolyHaven assets (textures, HDRIs, models)
• Sketchfab models (requires API key)
• AI 3D generation services (Hyper3D, Hunyuan3D)
• Local-only mode works without internet (core features only)

Quick Start¶

For experienced users, here's the fastest path to get started:

# 1. Install BlenderForge
pip install blenderforge

# 2. Verify installation
blenderforge --version

# 3. Download addon.py from repository and install in Blender
# Edit → Preferences → Add-ons → Install...

# 4. Configure your AI client (Claude Desktop example)
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
# {
#   "mcpServers": {
#     "blenderforge": {
#       "command": "blenderforge"
#     }
#   }
# }

# 5. In Blender: Press N → BlenderForge tab → "Connect to MCP server"
# 6. Restart your AI assistant
# 7. Ask: "What objects are in my Blender scene?"

Step 1: Install BlenderForge¶

Choose the installation method that best fits your workflow.

Option A: Install from PyPI (Recommended)¶

The simplest method for most users:

pip install blenderforge

Platform-Specific Commands¶

macOS / Linux:

# Using pip (may require pip3)
pip3 install blenderforge

# Or if pip is aliased to pip3
pip install blenderforge

Windows (Command Prompt):

pip install blenderforge

Windows (PowerShell):

pip install blenderforge

Option B: Install with UV (Fast Package Manager)¶

UV is a modern, fast Python package manager:

# Install UV first (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install BlenderForge
uv pip install blenderforge

Option C: Install with pipx (Isolated Environment)¶

pipx installs packages in isolated environments:

# Install pipx first (if not installed)
pip install pipx
pipx ensurepath

# Install BlenderForge
pipx install blenderforge

Option D: Install from Source (Development)¶

For contributors or those who need the latest features:

# Clone the repository
git clone https://github.com/mithun50/blenderforge.git
cd blenderforge

# Create virtual environment (recommended)
python -m venv .venv

# Activate virtual environment
# macOS/Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# Install in development mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Verify Installation¶

After installation, verify BlenderForge is working:

# Check version
blenderforge --version

# Should output something like:
# BlenderForge v0.1.0

If blenderforge command is not found:

1. Check if pip installed to a user directory:

   # Find where pip installed it
   pip show blenderforge
   
   # Add the Scripts/bin directory to PATH
   # Look for "Location:" in the output
   

2. Try running as a module:

   python -m blenderforge --version
   

3. Check PATH environment variable:

   # macOS/Linux
   echo $PATH
   
   # Windows
   echo %PATH%
   

Step 2: Install the Blender Addon¶

The Blender addon receives commands from BlenderForge and executes them inside Blender.

Download the Addon¶

Direct Download (Recommended)¶

⬇️ Download addon.py (Right-click → Save Link As...)

Or use the command line:

# macOS/Linux
curl -O https://raw.githubusercontent.com/mithun50/Blender-Forge/main/addon.py

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/mithun50/Blender-Forge/main/addon.py" -OutFile "addon.py"

# Windows (Command Prompt with curl)
curl -O https://raw.githubusercontent.com/mithun50/Blender-Forge/main/addon.py

Alternative Download Methods¶

1. From GitHub Repository:
2. Go to BlenderForge Repository
3. Click on addon.py file

4. Click the Download button (↓) or Raw button, then save the page

5. Clone the Repository:

   git clone https://github.com/mithun50/blenderforge.git
   # addon.py is in the root directory
   

Install in Blender¶

GUI Method (Recommended)¶

1. Open Blender

2. Open Preferences:

3. Go to Edit → Preferences (or press Ctrl+, / Cmd+,)

4. Navigate to Add-ons:

5. Click on the Add-ons tab in the left sidebar

6. Install the Addon:

7. Click the Install... button (top-right corner)
8. Navigate to where you downloaded addon.py
9. Select addon.py

10. Click Install Add-on

11. Enable the Addon:

12. After installation, search for "BlenderForge" in the search box
13. Check the checkbox next to "BlenderForge" to enable it

14. You should see a checkmark appear

15. Save Preferences:

16. Click the hamburger menu (☰) at the bottom-left
17. Select Save Preferences
18. This ensures the addon loads automatically every time you start Blender

Visual Guide¶

┌─────────────────────────────────────────────────────────────────┐
│  Blender Preferences                                      [X]  │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐                                                   │
│  │Interface │   Search: [BlenderForge        ]    [Install...] │
│  │Themes    │                                                   │
│  │Viewport  │   ☑ BlenderForge                                  │
│  │Lights    │     AI-powered Blender control via MCP            │
│  │Editing   │     Version: 1.0.0                                │
│  │Animation │     Author: BlenderForge Team                     │
│  │▶Add-ons  │                                                   │
│  │Input     │   ┌─────────────────────────────────────────────┐ │
│  │Navigation│   │ Preferences:                                │ │
│  │Keymap    │   │  Port: [9876    ]                           │ │
│  │System    │   │  ☑ Use PolyHaven                            │ │
│  │Save&Load │   │  ☐ Use Sketchfab  API Key: [••••••••••]     │ │
│  │File Paths│   │  ☐ Use Hyper3D    API Key: [          ]     │ │
│  └──────────┘   └─────────────────────────────────────────────┘ │
│                                                                 │
│  [☰] ────────────────────────────────────────── [Save Preferences]
└─────────────────────────────────────────────────────────────────┘

Command Line Method (Advanced)¶

For automated installation, copy addon.py directly to Blender's addon directory:

macOS:

cp addon.py ~/Library/Application\ Support/Blender/4.0/scripts/addons/

Windows (PowerShell):

Copy-Item addon.py "$env:APPDATA\Blender Foundation\Blender\4.0\scripts\addons\"

Linux:

cp addon.py ~/.config/blender/4.0/scripts/addons/

Then enable in Blender:

Edit → Preferences → Add-ons → Search "BlenderForge" → Enable checkbox

Verify Addon Installation¶

1. Check Sidebar Panel:
2. Press N to open the sidebar (right side of 3D viewport)
3. Look for the BlenderForge tab

4. You should see:

   • Server status indicator
   • Port configuration
   • Connect/Disconnect button
   • Integration checkboxes (PolyHaven, Sketchfab, etc.)

5. Check Blender Console for Confirmation:

6. Windows: Window → Toggle System Console
7. macOS/Linux: Launch Blender from terminal to see output

8. Look for message: "BlenderForge addon registered"

9. Test the Panel:

10. The panel should display "Status: Disconnected" initially
11. This is normal - you'll connect after configuring your AI client

Step 3: Configure Your AI Assistant¶

BlenderForge uses the Model Context Protocol (MCP) to communicate with AI assistants. Each AI client has its own configuration method.

Quick Configuration Reference¶

Claude Desktop Configuration¶

The most common setup. Edit the config file for your platform:

macOS:

# Open or create the config file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

# Open in Notepad
notepad %APPDATA%\Claude\claude_desktop_config.json

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "blenderforge": {
      "command": "blenderforge"
    }
  }
}

With Python path (if command not in PATH):

{
  "mcpServers": {
    "blenderforge": {
      "command": "/path/to/python",
      "args": ["-m", "blenderforge"]
    }
  }
}

With environment variables:

{
  "mcpServers": {
    "blenderforge": {
      "command": "blenderforge",
      "env": {
        "BLENDER_PORT": "9876",
        "DISABLE_TELEMETRY": "true"
      }
    }
  }
}

Other AI Clients¶

For detailed setup instructions for all supported AI clients, see AI Clients.

Step 4: Connect Everything¶

Now let's connect all the pieces together.

Connection Flow¶

AI Assistant  ─MCP Protocol→  BlenderForge Server  ─TCP Socket→  Blender Addon
    │                              │                                  │
    │  JSON-RPC over stdio         │  localhost:9876                  │
    │                              │                                  │
    └──────── Tool Calls ──────────┴────── Commands ──────────────────┘

Start the Connection¶

1. Open Blender with the addon enabled

2. Open the BlenderForge Panel:

3. Press N to open the sidebar

4. Click the BlenderForge tab

5. Configure Port (if needed):

6. Default port is 9876

7. Change if you have conflicts

8. Start the Server:

9. Click "Connect to MCP server"

10. Status should change to "Connected"

11. Restart Your AI Assistant:

12. Close and reopen your AI client completely
13. MCP servers are loaded at startup

Verify Connection¶

Ask your AI assistant:

What objects are in my Blender scene?

Expected Response: The AI should query Blender and return information about objects in your scene. For a new scene, this typically includes: - Camera - Light (or Lamp) - Cube (default cube)

If it works: Congratulations! BlenderForge is connected.

If it doesn't work: See Troubleshooting.

Step 5: Try It Out¶

Here are examples organized by complexity.

Basic Scene Operations¶

"What's in my scene?"
"Get information about the current scene"
"List all objects in the scene"

Object Creation¶

"Add a cube at position (2, 0, 0)"
"Create a sphere with radius 2"
"Add a cylinder at the origin"
"Create a plane for the ground"

Object Manipulation¶

"Move the cube to (0, 0, 3)"
"Rotate the sphere 45 degrees on the Z axis"
"Scale the cube by 2"
"Delete the default cube"

Screenshots¶

"Take a screenshot of the viewport"
"Capture the current render view"

PolyHaven Assets¶

First enable PolyHaven in the BlenderForge panel, then:

"Search for wood textures on PolyHaven"
"Download the 'wood_floor_deck' texture"
"Apply the wood texture to the cube"
"Set up studio HDRI lighting"
"Find outdoor HDRIs"

AI-Powered Features¶

BlenderForge includes built-in AI features that don't require external API keys:

AI Material Generator:

"Generate a rusty metal material"
"Create a glowing neon material"
"Make a realistic wood material for the table"

Natural Language Modeling:

"Create a red cube 2 meters tall"
"Add a blue sphere at position 3, 0, 0"
"Make a small green cylinder"

Scene Analysis:

"Analyze my scene composition"
"Give me feedback on my scene"
"What could improve this scene?"

Auto-Rigging:

"Auto-rig the character mesh"
"Create an armature for the humanoid"

Advanced Python Execution¶

For complete control, execute Python code directly:

"Run this Python code in Blender:
import bpy
for i in range(5):
    bpy.ops.mesh.primitive_uv_sphere_add(location=(i*2, 0, 0))"

"Execute in Blender:
import bpy
# Create a new material
mat = bpy.data.materials.new('Red_Material')
mat.use_nodes = True
mat.node_tree.nodes['Principled BSDF'].inputs['Base Color'].default_value = (1, 0, 0, 1)"

Environment Variables¶

Customize BlenderForge behavior with environment variables.

Available Variables¶

Setting Environment Variables¶

macOS / Linux (temporary):

export BLENDER_PORT=9877
export DISABLE_TELEMETRY=true
blenderforge

macOS / Linux (permanent - add to shell profile):

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export BLENDER_PORT=9877
export DISABLE_TELEMETRY=true

Windows (Command Prompt - temporary):

set BLENDER_PORT=9877
set DISABLE_TELEMETRY=true
blenderforge

Windows (PowerShell - temporary):

$env:BLENDER_PORT = "9877"
$env:DISABLE_TELEMETRY = "true"
blenderforge

Windows (permanent - System Properties): 1. Open "Environment Variables" in System Properties 2. Add new user or system variables

In MCP Configuration¶

You can also set environment variables in your AI client's MCP config:

{
  "mcpServers": {
    "blenderforge": {
      "command": "blenderforge",
      "env": {
        "BLENDER_PORT": "9877",
        "DISABLE_TELEMETRY": "true",
        "BLENDERFORGE_DEBUG": "true"
      }
    }
  }
}

Advanced Configuration¶

Running Multiple Blender Instances¶

To connect to multiple Blender instances:

1. Start each Blender with different ports:
2. Blender 1: Port 9876 (default)
3. Blender 2: Port 9877

4. Blender 3: Port 9878

5. Configure multiple MCP servers:

   {
     "mcpServers": {
       "blender1": {
         "command": "blenderforge",
         "env": { "BLENDER_PORT": "9876" }
       },
       "blender2": {
         "command": "blenderforge",
         "env": { "BLENDER_PORT": "9877" }
       }
     }
   }
   

Remote Blender Connection¶

For advanced use cases (same network):

1. On the Blender machine:
2. Modify addon to bind to 0.0.0.0 instead of localhost

3. Configure firewall to allow connections

4. On the AI client machine:

   {
     "mcpServers": {
       "blenderforge": {
         "command": "blenderforge",
         "env": {
           "BLENDER_HOST": "192.168.1.100",
           "BLENDER_PORT": "9876"
         }
       }
     }
   }
   

⚠️ Security Warning: Remote connections are not encrypted. Only use on trusted networks.

Using Virtual Environments¶

If you installed BlenderForge in a virtual environment:

{
  "mcpServers": {
    "blenderforge": {
      "command": "/path/to/venv/bin/blenderforge"
    }
  }
}

Or use the Python interpreter:

{
  "mcpServers": {
    "blenderforge": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "blenderforge"]
    }
  }
}

Platform-Specific Notes¶

macOS¶

Python Installation: - Homebrew: brew install python@3.11 - Official installer from python.org

Common Issues: - If blenderforge not found, check ~/Library/Python/3.x/bin is in PATH - System Integrity Protection may block some operations

Blender Location: - Default: /Applications/Blender.app - Addon directory: ~/Library/Application Support/Blender/4.0/scripts/addons/

Windows¶

Python Installation: - Download from python.org - Important: Check "Add Python to PATH" during installation

Common Issues: - Run Command Prompt as Administrator if permission issues - Use forward slashes or escaped backslashes in paths

Blender Location: - Default: C:\Program Files\Blender Foundation\Blender 4.0 - Addon directory: %APPDATA%\Blender Foundation\Blender\4.0\scripts\addons\

Linux¶

Python Installation:

# Ubuntu/Debian
sudo apt install python3.11 python3.11-venv python3-pip

# Fedora
sudo dnf install python3.11 python3-pip

# Arch
sudo pacman -S python python-pip

Blender Installation: - Snap: sudo snap install blender --classic - Flatpak: flatpak install flathub org.blender.Blender - Official tarball from blender.org

Common Issues: - Snap/Flatpak Blender may have restricted file access - Check permissions on addon directory

Blender Location: - System: /usr/share/blender/ - User addon directory: ~/.config/blender/4.0/scripts/addons/

Next Steps¶

Now that BlenderForge is installed and connected:

Learn More¶

Enable Integrations¶

In the BlenderForge panel: - ✅ PolyHaven - Free textures, HDRIs, models - ✅ Sketchfab - 3D model marketplace (requires API key) - ✅ Hyper3D Rodin - AI 3D generation (requires API key) - ✅ Hunyuan3D - AI 3D generation (requires Tencent credentials)

Join the Community¶

• GitHub Repository
• GitHub Issues - Report bugs, request features
• GitHub Discussions - Ask questions, share creations

Having Issues?¶

See Troubleshooting for common problems and solutions.

Common quick fixes: 1. Restart both Blender and your AI assistant 2. Check the port is the same in Blender panel and MCP config 3. Verify blenderforge command is in PATH 4. Check Blender console for error messages