# blender-remote
## Overview
**Purpose**: Enable complex Blender automation through LLM-assisted Python development, bridging the gap between AI-generated Blender scripts and external Python tools.
**Intended Users**:
- Developers who need complex Blender automation but lack time to master Blender's Python API
- Users uncomfortable writing Blender-side Python code within Blender's basic text editor
- Developers who rely heavily on LLMs for code generation and want to automate Blender tasks
**Our Solution**:
- Allow LLMs to generate Blender-side Python code and help wrap it into external Python APIs
- Provide background mode execution for full automation and batch processing
- **We DO NOT try to map all Blender Python API to Python or MCP** - instead, we provide infrastructure for users to develop their own Python tools to interact with Blender with LLM assistance
- **Ultimate outcome**: Use your VSCode with your own Python to control Blender, not constrained by Blender's barebone Python environment and editor, write complex Blender automation projects with ease
**System Architecture**:
- **`BLD_Remote_MCP`** - Blender addon using JSON-RPC to communicate with external callers
- **MCP Server** - Forwards MCP commands from LLM IDEs (VSCode, Claude, Cursor) to Blender addon
- **Python Client** - Direct control of Blender addon, bypassing MCP server for automation scripts
**Key Features**:
- Seamless bridge between LLM-generated Blender-side code and external Python APIs
- Simultaneous LLM and Python client access with smooth code transition workflow
- LLM-assisted wrapper code generation for converting Blender scripts to Python APIs
- Background mode support for automation and batch processing
- Cross-platform support: Windows, Linux, macOS
**Caution**: This code is primarily written with AI assistance. Use at your own risk.
## Usage
### Installation
**Install the package**:
```bash
pip install blender-remote
```
**Install uv (required for MCP server)**:
```bash
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Basic Usage
#### The CLI Approach
Use `blender-remote-cli` to set up and manage Blender integration:
**1. Initialize and install addon**:
```bash
# Auto-detect Blender (Windows/macOS) or specify path
blender-remote-cli init
# Install the addon automatically (recommended)
blender-remote-cli install
```
> **Note for manual installation**: If you prefer to install the addon manually or inspect its source code, you can export it first:
> ```bash
> blender-remote-cli export --content=addon -o ./exported_addon
> ```
> This creates a `bld_remote_mcp` directory inside `./exported_addon`. You can then zip this directory and install it via Blender's `Edit > Preferences > Add-ons`.
**2. Verify installation in Blender GUI**:
- Open Blender → Edit → Preferences → Add-ons
- Search for "BLD Remote MCP" - should be enabled
**3. Configure service settings (optional, before starting)**:
```bash
# Configure custom port (default is 6688)
blender-remote-cli config set mcp_service.default_port=7777
# Configure logging level
blender-remote-cli config set mcp_service.log_level=DEBUG
# View current configuration
blender-remote-cli config get mcp_service.default_port
```
**4. Start Blender with service**:
```bash
# GUI mode with service
blender-remote-cli start
# Background mode for automation
blender-remote-cli start --background
# Load specific scene
blender-remote-cli start --scene=my_project.blend
```
**5. Execute commands on running Blender**:
```bash
# Execute Python code directly
blender-remote-cli execute -c "import bpy; bpy.ops.mesh.primitive_cube_add(location=(2, 0, 0))"
# Execute with custom port
blender-remote-cli execute -c 'import bpy; print(f"Blender {bpy.app.version_string}")' --port 7888
# Execute Python file
blender-remote-cli execute my_script.py
# Complex code with base64 encoding (recommended for multiline code)
blender-remote-cli execute -c "import bpy; [bpy.ops.mesh.primitive_cube_add(location=(i*2, 0, 0)) for i in range(3)]" --use-base64
```
**6. Export addon or scripts for manual use**:
```bash
# Export addon source code for inspection or manual installation
blender-remote-cli export --content=addon -o ./exported_addon
# Export the keep-alive script for custom background startup
blender-remote-cli export --content=keep-alive.py -o .
```
#### The MCP Server Approach
For LLM IDEs like VSCode, Claude Desktop, or Cursor:
**1. Install Blender addon first** (see CLI approach above)
**2. Start Blender with service**:
```bash
blender-remote-cli start
```
**3. Configure your LLM IDE**:
**VSCode settings.json**:
```json
{
"mcpServers": {
"blender-remote": {
"command": "uvx",
"args": ["blender-remote"]
}
}
}
```
**Custom host/port configuration**:
```json
{
"mcpServers": {
"blender-remote": {
"command": "uvx",
"args": ["blender-remote", "--host", "127.0.0.1", "--port", "6688"]
}
}
}
```
**4. Use with LLM**:
- "What objects are in the current Blender scene?"
- "Create a metallic blue cube at position (2, 0, 0)"
- "Export the current scene as GLB format"
- "Help me create a Python function to generate a grid of cubes"
#### The Python Client Approach
For direct Python automation scripts:
```python
import blender_remote
# Connect to running Blender service
client = blender_remote.connect_to_blender(port=6688)
# Execute Blender Python code directly
result = client.execute_python("bpy.ops.mesh.primitive_cube_add(location=(2, 0, 0))")
# Use scene manager for higher-level operations
scene_manager = blender_remote.create_scene_manager(client)
scene_manager.set_camera_location(location=(7, -7, 5), target=(0, 0, 0))
# Get scene information
scene_info = client.get_scene_info()
print(f"Scene has {len(scene_info['objects'])} objects")
```
### Advanced Usage
#### Using LLM to Develop Python Tools for Blender
**Example workflow**:
1. **Ask LLM**: "Create Blender code to generate a spiral of cubes"
2. **LLM generates**: Blender-side Python code using `bpy` operations
3. **Test in Blender**: Use MCP tools to execute and refine the code
4. **Ask LLM**: "Wrap this into a Python function I can call from external scripts"
5. **LLM creates wrapper**:
```python
def create_cube_spiral(client, count=10, radius=3):
code = f"""
import bpy
import math
for i in range({count}):
angle = i * (2 * math.pi / {count})
x = {radius} * math.cos(angle)
y = {radius} * math.sin(angle)
z = i * 0.5
bpy.ops.mesh.primitive_cube_add(location=(x, y, z))
"""
return client.execute_python(code)
# Use the wrapper
client = blender_remote.connect_to_blender()
create_cube_spiral(client, count=15, radius=5)
```
#### Batch Processing Using Background Mode
For full control over the background process, you can export the keep-alive script, modify it if needed, and run it directly with Blender. This is useful for custom startup logic or integration into larger automation frameworks.
**1. Export the keep-alive script**
```bash
blender-remote-cli export --content=keep-alive.py -o .
```
**2. Start Blender with the script and required environment variables**
The addon requires environment variables to know which port to use and to enable auto-start.
**On Linux/macOS:**
```bash
# Set environment variables and start Blender in the background
export BLD_REMOTE_MCP_PORT=7788
export BLD_REMOTE_MCP_START_NOW=1
export BLD_REMOTE_LOG_LEVEL=DEBUG # Optional: for detailed logs
blender --background --python keep-alive.py &
```
**On Windows (Command Prompt):**
```cmd
C:\> set BLD_REMOTE_MCP_PORT=7788
C:\> set BLD_REMOTE_MCP_START_NOW=1
C:\> set BLD_REMOTE_LOG_LEVEL=DEBUG
C:\> start /b blender --background --python keep-alive.py
```
**On Windows (PowerShell):**
```powershell
PS C:\> $env:BLD_REMOTE_MCP_PORT="7788"
PS C:\> $env:BLD_REMOTE_MCP_START_NOW="1"
PS C:\> $env:BLD_REMOTE_LOG_LEVEL="DEBUG"
PS C:\> Start-Process blender -ArgumentList "--background", "--python", "keep-alive.py" -NoNewWindow
```
The Python client can then connect to this manually started instance on the specified port.
**Automated batch workflow (using the CLI to start)**:
```python
import blender_remote
import subprocess
import time
import os
# Start background Blender process using CLI (avoids path issues)
port = 7888
process = subprocess.Popen([
"python", "-m", "blender_remote.cli", "start", "--background", "--port", str(port)
])
# Wait for service to start up
time.sleep(3)
# Connect to the background instance
client = blender_remote.connect_to_blender(port=port)
# Process multiple scene files
scene_dir = "tmp/test-scenes"
input_files = ["scene1.blend", "scene2.blend", "scene3.blend"]
for scene_file in input_files:
scene_path = os.path.join(scene_dir, scene_file)
scene_path_abs = os.path.abspath(scene_path)
print(f"Processing {scene_file}...")
# Load scene
client.execute_python(f'bpy.ops.wm.open_mainfile(filepath="{scene_path_abs.replace(os.sep, "/")}")')
# Process scene (your custom operations)
client.execute_python("bpy.ops.mesh.primitive_cube_add(location=(0, 0, 2))")
client.execute_python("bpy.ops.mesh.primitive_uv_sphere_add(location=(2, 0, 0))")
# Export result
output_file = scene_file.replace('.blend', '.glb')
output_path = os.path.abspath(f"tmp/{output_file}")
client.execute_python(f'bpy.ops.export_scene.gltf(filepath="{output_path.replace(os.sep, "/")}")')
print(f"Exported {output_file}")
# Gracefully exit Blender
client.execute_python("bpy.ops.wm.quit_blender()")
process.wait() # Wait for process to fully exit
```
## Documentation
- **Full Documentation**: [https://igamenovoer.github.io/blender-remote/](https://igamenovoer.github.io/blender-remote/)
- **Examples**: [examples/](https://github.com/igamenovoer/blender-remote/tree/main/examples)
- **Issues**: [Report bugs](https://github.com/igamenovoer/blender-remote/issues)
## Credits
Built upon the [blender-mcp](https://github.com/ahujasid/blender-mcp) project with enhanced background mode support, thread-safe operations, and production deployment capabilities.
## License
[MIT License](LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "blender-remote",
"maintainer": "blender-remote contributors",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "blender, remote-control, 3d, automation, mcp, api",
"author": "blender-remote contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8b/15/adf56080916b9de219c0fe6af3c5ff15d0759189f9ac4b832ab414ea18e1/blender_remote-1.2.5.tar.gz",
"platform": null,
"description": "# blender-remote\n\n## Overview\n\n**Purpose**: Enable complex Blender automation through LLM-assisted Python development, bridging the gap between AI-generated Blender scripts and external Python tools.\n\n**Intended Users**:\n- Developers who need complex Blender automation but lack time to master Blender's Python API\n- Users uncomfortable writing Blender-side Python code within Blender's basic text editor\n- Developers who rely heavily on LLMs for code generation and want to automate Blender tasks\n\n**Our Solution**:\n- Allow LLMs to generate Blender-side Python code and help wrap it into external Python APIs\n- Provide background mode execution for full automation and batch processing\n- **We DO NOT try to map all Blender Python API to Python or MCP** - instead, we provide infrastructure for users to develop their own Python tools to interact with Blender with LLM assistance\n- **Ultimate outcome**: Use your VSCode with your own Python to control Blender, not constrained by Blender's barebone Python environment and editor, write complex Blender automation projects with ease\n\n**System Architecture**:\n- **`BLD_Remote_MCP`** - Blender addon using JSON-RPC to communicate with external callers\n- **MCP Server** - Forwards MCP commands from LLM IDEs (VSCode, Claude, Cursor) to Blender addon \n- **Python Client** - Direct control of Blender addon, bypassing MCP server for automation scripts\n\n\n\n**Key Features**:\n- Seamless bridge between LLM-generated Blender-side code and external Python APIs\n- Simultaneous LLM and Python client access with smooth code transition workflow\n- LLM-assisted wrapper code generation for converting Blender scripts to Python APIs\n- Background mode support for automation and batch processing\n- Cross-platform support: Windows, Linux, macOS\n\n**Caution**: This code is primarily written with AI assistance. Use at your own risk.\n\n## Usage\n\n### Installation\n\n**Install the package**:\n```bash\npip install blender-remote\n```\n\n**Install uv (required for MCP server)**:\n```bash\n# Windows (PowerShell)\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Linux/macOS\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### Basic Usage\n\n#### The CLI Approach\n\nUse `blender-remote-cli` to set up and manage Blender integration:\n\n**1. Initialize and install addon**:\n```bash\n# Auto-detect Blender (Windows/macOS) or specify path\nblender-remote-cli init\n\n# Install the addon automatically (recommended)\nblender-remote-cli install\n```\n\n> **Note for manual installation**: If you prefer to install the addon manually or inspect its source code, you can export it first:\n> ```bash\n> blender-remote-cli export --content=addon -o ./exported_addon\n> ```\n> This creates a `bld_remote_mcp` directory inside `./exported_addon`. You can then zip this directory and install it via Blender's `Edit > Preferences > Add-ons`.\n\n**2. Verify installation in Blender GUI**:\n- Open Blender \u2192 Edit \u2192 Preferences \u2192 Add-ons\n- Search for \"BLD Remote MCP\" - should be enabled\n\n**3. Configure service settings (optional, before starting)**:\n```bash\n# Configure custom port (default is 6688)\nblender-remote-cli config set mcp_service.default_port=7777\n\n# Configure logging level \nblender-remote-cli config set mcp_service.log_level=DEBUG\n\n# View current configuration\nblender-remote-cli config get mcp_service.default_port\n```\n\n**4. Start Blender with service**:\n```bash\n# GUI mode with service\nblender-remote-cli start\n\n# Background mode for automation \nblender-remote-cli start --background\n\n# Load specific scene\nblender-remote-cli start --scene=my_project.blend\n```\n\n**5. Execute commands on running Blender**:\n```bash\n# Execute Python code directly\nblender-remote-cli execute -c \"import bpy; bpy.ops.mesh.primitive_cube_add(location=(2, 0, 0))\"\n\n# Execute with custom port\nblender-remote-cli execute -c 'import bpy; print(f\"Blender {bpy.app.version_string}\")' --port 7888\n\n# Execute Python file\nblender-remote-cli execute my_script.py\n\n# Complex code with base64 encoding (recommended for multiline code)\nblender-remote-cli execute -c \"import bpy; [bpy.ops.mesh.primitive_cube_add(location=(i*2, 0, 0)) for i in range(3)]\" --use-base64\n```\n\n**6. Export addon or scripts for manual use**:\n```bash\n# Export addon source code for inspection or manual installation\nblender-remote-cli export --content=addon -o ./exported_addon\n\n# Export the keep-alive script for custom background startup\nblender-remote-cli export --content=keep-alive.py -o .\n```\n\n#### The MCP Server Approach\n\nFor LLM IDEs like VSCode, Claude Desktop, or Cursor:\n\n**1. Install Blender addon first** (see CLI approach above)\n\n**2. Start Blender with service**:\n```bash\nblender-remote-cli start\n```\n\n**3. Configure your LLM IDE**:\n\n**VSCode settings.json**:\n```json\n{\n \"mcpServers\": {\n \"blender-remote\": {\n \"command\": \"uvx\",\n \"args\": [\"blender-remote\"]\n }\n }\n}\n```\n\n**Custom host/port configuration**:\n```json\n{\n \"mcpServers\": {\n \"blender-remote\": {\n \"command\": \"uvx\", \n \"args\": [\"blender-remote\", \"--host\", \"127.0.0.1\", \"--port\", \"6688\"]\n }\n }\n}\n```\n\n**4. Use with LLM**:\n- \"What objects are in the current Blender scene?\"\n- \"Create a metallic blue cube at position (2, 0, 0)\"\n- \"Export the current scene as GLB format\"\n- \"Help me create a Python function to generate a grid of cubes\"\n\n#### The Python Client Approach\n\nFor direct Python automation scripts:\n\n```python\nimport blender_remote\n\n# Connect to running Blender service\nclient = blender_remote.connect_to_blender(port=6688)\n\n# Execute Blender Python code directly\nresult = client.execute_python(\"bpy.ops.mesh.primitive_cube_add(location=(2, 0, 0))\")\n\n# Use scene manager for higher-level operations\nscene_manager = blender_remote.create_scene_manager(client)\nscene_manager.set_camera_location(location=(7, -7, 5), target=(0, 0, 0))\n\n# Get scene information\nscene_info = client.get_scene_info()\nprint(f\"Scene has {len(scene_info['objects'])} objects\")\n```\n\n### Advanced Usage\n\n#### Using LLM to Develop Python Tools for Blender\n\n**Example workflow**:\n\n1. **Ask LLM**: \"Create Blender code to generate a spiral of cubes\"\n2. **LLM generates**: Blender-side Python code using `bpy` operations\n3. **Test in Blender**: Use MCP tools to execute and refine the code\n4. **Ask LLM**: \"Wrap this into a Python function I can call from external scripts\"\n5. **LLM creates wrapper**:\n\n```python\ndef create_cube_spiral(client, count=10, radius=3):\n code = f\"\"\"\nimport bpy\nimport math\n\nfor i in range({count}):\n angle = i * (2 * math.pi / {count})\n x = {radius} * math.cos(angle)\n y = {radius} * math.sin(angle)\n z = i * 0.5\n bpy.ops.mesh.primitive_cube_add(location=(x, y, z))\n\"\"\"\n return client.execute_python(code)\n\n# Use the wrapper\nclient = blender_remote.connect_to_blender()\ncreate_cube_spiral(client, count=15, radius=5)\n```\n\n#### Batch Processing Using Background Mode\n\nFor full control over the background process, you can export the keep-alive script, modify it if needed, and run it directly with Blender. This is useful for custom startup logic or integration into larger automation frameworks.\n\n**1. Export the keep-alive script**\n```bash\nblender-remote-cli export --content=keep-alive.py -o .\n```\n\n**2. Start Blender with the script and required environment variables**\n\nThe addon requires environment variables to know which port to use and to enable auto-start.\n\n**On Linux/macOS:**\n```bash\n# Set environment variables and start Blender in the background\nexport BLD_REMOTE_MCP_PORT=7788\nexport BLD_REMOTE_MCP_START_NOW=1\nexport BLD_REMOTE_LOG_LEVEL=DEBUG # Optional: for detailed logs\nblender --background --python keep-alive.py &\n```\n\n**On Windows (Command Prompt):**\n```cmd\nC:\\> set BLD_REMOTE_MCP_PORT=7788\nC:\\> set BLD_REMOTE_MCP_START_NOW=1\nC:\\> set BLD_REMOTE_LOG_LEVEL=DEBUG\nC:\\> start /b blender --background --python keep-alive.py\n```\n\n**On Windows (PowerShell):**\n```powershell\nPS C:\\> $env:BLD_REMOTE_MCP_PORT=\"7788\"\nPS C:\\> $env:BLD_REMOTE_MCP_START_NOW=\"1\"\nPS C:\\> $env:BLD_REMOTE_LOG_LEVEL=\"DEBUG\"\nPS C:\\> Start-Process blender -ArgumentList \"--background\", \"--python\", \"keep-alive.py\" -NoNewWindow\n```\n\nThe Python client can then connect to this manually started instance on the specified port.\n\n**Automated batch workflow (using the CLI to start)**:\n\n```python\nimport blender_remote\nimport subprocess\nimport time\nimport os\n\n# Start background Blender process using CLI (avoids path issues)\nport = 7888\nprocess = subprocess.Popen([\n \"python\", \"-m\", \"blender_remote.cli\", \"start\", \"--background\", \"--port\", str(port)\n])\n\n# Wait for service to start up\ntime.sleep(3)\n\n# Connect to the background instance\nclient = blender_remote.connect_to_blender(port=port)\n\n# Process multiple scene files\nscene_dir = \"tmp/test-scenes\"\ninput_files = [\"scene1.blend\", \"scene2.blend\", \"scene3.blend\"]\n\nfor scene_file in input_files:\n scene_path = os.path.join(scene_dir, scene_file)\n scene_path_abs = os.path.abspath(scene_path)\n \n print(f\"Processing {scene_file}...\")\n \n # Load scene\n client.execute_python(f'bpy.ops.wm.open_mainfile(filepath=\"{scene_path_abs.replace(os.sep, \"/\")}\")')\n \n # Process scene (your custom operations)\n client.execute_python(\"bpy.ops.mesh.primitive_cube_add(location=(0, 0, 2))\")\n client.execute_python(\"bpy.ops.mesh.primitive_uv_sphere_add(location=(2, 0, 0))\")\n \n # Export result\n output_file = scene_file.replace('.blend', '.glb')\n output_path = os.path.abspath(f\"tmp/{output_file}\")\n client.execute_python(f'bpy.ops.export_scene.gltf(filepath=\"{output_path.replace(os.sep, \"/\")}\")')\n \n print(f\"Exported {output_file}\")\n\n# Gracefully exit Blender\nclient.execute_python(\"bpy.ops.wm.quit_blender()\")\nprocess.wait() # Wait for process to fully exit\n```\n\n## Documentation\n\n- **Full Documentation**: [https://igamenovoer.github.io/blender-remote/](https://igamenovoer.github.io/blender-remote/)\n- **Examples**: [examples/](https://github.com/igamenovoer/blender-remote/tree/main/examples)\n- **Issues**: [Report bugs](https://github.com/igamenovoer/blender-remote/issues)\n\n## Credits\n\nBuilt upon the [blender-mcp](https://github.com/ahujasid/blender-mcp) project with enhanced background mode support, thread-safe operations, and production deployment capabilities.\n\n## License\n\n[MIT License](LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automate Blender workflows with external Python control, background operation, and LLM integration",
"version": "1.2.5",
"project_urls": {
"Bug Tracker": "https://github.com/igamenovoer/blender-remote/issues",
"Documentation": "https://igamenovoer.github.io/blender-remote/",
"Homepage": "https://github.com/igamenovoer/blender-remote",
"Repository": "https://github.com/igamenovoer/blender-remote.git"
},
"split_keywords": [
"blender",
" remote-control",
" 3d",
" automation",
" mcp",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c4e06e7cc96d89f7ebf4a0808480864cb0c01e2d35d67c84a8a26c2170e2996f",
"md5": "638991a242c58f1defe7b4f5731df534",
"sha256": "dae4fca8a826ebd46a1e8ce03908fa00a4908acae77f4243c48130e3f560eaee"
},
"downloads": -1,
"filename": "blender_remote-1.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "638991a242c58f1defe7b4f5731df534",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 69383,
"upload_time": "2025-07-16T19:31:42",
"upload_time_iso_8601": "2025-07-16T19:31:42.906821Z",
"url": "https://files.pythonhosted.org/packages/c4/e0/6e7cc96d89f7ebf4a0808480864cb0c01e2d35d67c84a8a26c2170e2996f/blender_remote-1.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8b15adf56080916b9de219c0fe6af3c5ff15d0759189f9ac4b832ab414ea18e1",
"md5": "d912fbbbe50f84d7c0a49be8a73f4009",
"sha256": "b1bf86458ad1879bff75644163ff67da42024e2f0f39e5f5c79b1786226c9290"
},
"downloads": -1,
"filename": "blender_remote-1.2.5.tar.gz",
"has_sig": false,
"md5_digest": "d912fbbbe50f84d7c0a49be8a73f4009",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 136043,
"upload_time": "2025-07-16T19:31:43",
"upload_time_iso_8601": "2025-07-16T19:31:43.748296Z",
"url": "https://files.pythonhosted.org/packages/8b/15/adf56080916b9de219c0fe6af3c5ff15d0759189f9ac4b832ab414ea18e1/blender_remote-1.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 19:31:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "igamenovoer",
"github_project": "blender-remote",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "blender-remote"
}
JSON
