# blender-remote
🎯 **Automate Blender workflows with external Python control, background operation, and LLM integration**
blender-remote enables comprehensive Blender automation through multiple interfaces: auto-start service for external Python control, background mode operation for headless workflows, MCP server for LLM integration, and direct Python APIs. Perfect for CI/CD pipelines, render farms, and AI-assisted 3D workflows.
## ✨ Core Features
### 1. **🔧 Auto-Start Service for Blender Automation**
Enable headless Blender automation via external Python control:
```bash
# Set auto-start and launch Blender
export BLD_REMOTE_MCP_START_NOW=1
blender &
# External Python script controls Blender
python automation_script.py # Connects to port 6688, executes Blender operations
```
**Perfect for**: CI/CD pipelines, batch processing, render farms, automated asset generation
### 2. **🖥️ Background Mode Operation**
Run Blender completely headless with `blender --background`:
```python
# start_blender_bg.py - Script to enable service in background mode
import bpy
import bld_remote
bld_remote.start_mcp_service() # Starts service on port 6688
```
```bash
# Launch headless Blender with service
blender --background --python start_blender_bg.py &
# External control works identically
python your_automation.py # Same API, no GUI required
```
**Perfect for**: Headless servers, Docker containers, cloud rendering, automated workflows
### 3. **🤖 MCP Server for LLM Integration**
Standard Model Context Protocol server for AI assistant control:
```bash
uvx blender-remote # Starts MCP server for Claude, VSCode, Cursor, etc.
```
**Compatible with**: VSCode Claude, Claude Desktop, Cursor, and other MCP-compatible LLM IDEs
### 4. **🐍 Python Control Classes**
Direct Python API for programmatic Blender control *(coming soon)*
**Enables**: Native Python integration, custom automation tools, scripted workflows
## 🚀 Quick Start
### For Automation Users
**Auto-Start Service Pattern:**
```bash
# 1. Install addon (see details below) and set auto-start
export BLD_REMOTE_MCP_START_NOW=1
blender &
# 2. External Python automation via socket connection
python -c "
import socket, json
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(('127.0.0.1', 6688))
cmd = {'type': 'execute_code', 'params': {'code': 'bpy.ops.mesh.primitive_cube_add()'}}
sock.send(json.dumps(cmd).encode())
response = sock.recv(4096).decode()
print('Blender automated:', response)
sock.close()
"
```
**Background Mode Pattern:**
```bash
# 1. Create service startup script
echo 'import bld_remote; bld_remote.start_mcp_service()' > start_bg_service.py
# 2. Launch headless Blender with service
blender --background --python start_bg_service.py &
# 3. Same automation API works without GUI
python your_automation_script.py
```
### For LLM Users
### 1. Install Blender Add-on
#### Create the Add-on Zip File
```bash
# Navigate to the blender_addon directory from project root
cd blender-remote/ # Your cloned repository
cd blender_addon/
zip -r bld_remote_mcp.zip bld_remote_mcp/
```
**Note**: The `bld_remote_mcp.zip` file is not included in the repository and must be created by users from the `blender_addon/bld_remote_mcp/` directory.
#### Install via Blender GUI (Recommended)
1. **Open Blender**
2. Go to `Edit > Preferences` from the top menu bar
3. In the Preferences window, select the `Add-ons` tab
4. Click the `Install...` button (opens Blender's file browser)
5. Navigate to your `blender_addon/` directory and select `bld_remote_mcp.zip`
6. Click `Install Add-on`
7. **Search for "BLD Remote MCP" and enable it by ticking the checkbox**
#### Alternative: Manual Installation
```bash
# Copy directly to Blender addons directory
mkdir -p ~/.config/blender/4.4/scripts/addons/
cp -r bld_remote_mcp/ ~/.config/blender/4.4/scripts/addons/
```
#### Verify Installation
**Important**: This add-on has no visible GUI panel. Verify installation via system console:
**Windows**: `Window > Toggle System Console`
**macOS/Linux**: Start Blender from terminal
**Look for these log messages when enabling the add-on:**
```
=== BLD REMOTE MCP ADDON REGISTRATION STARTING ===
🚀 DEV-TEST-UPDATE: BLD Remote MCP v1.0.2 Loading!
...
✅ BLD Remote MCP addon registered successfully
=== BLD REMOTE MCP ADDON REGISTRATION COMPLETED ===
```
**If auto-start is enabled, you'll also see:**
```
✅ Starting server on port 6688
✅ BLD Remote server STARTED successfully on port 6688
Server is now listening for connections on 127.0.0.1:6688
```
### 2. Start Blender with Auto-Service
```bash
# Set environment variables and start Blender
export BLD_REMOTE_MCP_PORT=6688
export BLD_REMOTE_MCP_START_NOW=1
blender & # or "blender --background" for headless mode
```
### 3. Configure Your LLM IDE
**VSCode (with Claude/Cursor extensions):**
```json
{
"mcp": {
"servers": {
"blender-remote": {
"type": "stdio",
"command": "uvx",
"args": ["blender-remote"]
}
}
}
}
```
**Claude Desktop:**
```json
{
"mcpServers": {
"blender-remote": {
"command": "uvx",
"args": ["blender-remote"]
}
}
}
```
### 4. Start Creating with AI! 🎉
Your LLM can now:
- **Inspect scenes**: "What objects are in the current Blender scene?"
- **Execute code**: "Create a blue metallic cube at position (2, 0, 0)"
- **Take screenshots**: "Show me the current viewport"
- **Automate workflows**: "Create a donut tutorial scene with lighting"
## 🏗️ Architecture
**Multi-Interface Design for Different Automation Needs:**
```
External Python Scripts ←────┐
│
LLM IDE (VSCode/Claude) ←────┼─→ JSON-TCP (port 6688) ←─ BLD_Remote_MCP (Blender addon)
│ ↓
blender-remote (uvx MCP) ←───┘ Blender Python API
↓
Python Control Classes* ←─────────────────────────────→ Blender (GUI or --background)
```
**Three Control Pathways:**
1. **Direct Socket Connection**: External Python → JSON-TCP → Blender
2. **MCP Protocol**: LLM IDE → uvx blender-remote → JSON-TCP → Blender
3. **Python Classes**: Python → Direct API → Blender *(coming soon)*
## 📋 Available MCP Tools
| Tool | Description | Example Use |
|------|-------------|-------------|
| `get_scene_info()` | List all objects, materials, and scene properties | Scene analysis |
| `get_object_info(name)` | Get detailed object properties | Object inspection |
| `execute_blender_code(code)` | Run Python code in Blender context | Any Blender operation |
| `get_viewport_screenshot()` | Capture viewport as base64 image | Visual feedback |
| `check_connection_status()` | Verify service health | Debugging |
## 🔧 Advanced Usage
### Automation Integration
**CI/CD Pipeline Example:**
```yaml
# .github/workflows/blender-automation.yml
- name: Setup Blender Automation
run: |
export BLD_REMOTE_MCP_START_NOW=1
blender --background --python setup_service.py &
sleep 10 # Wait for service startup
python batch_render_pipeline.py
```
**Docker Container:**
```dockerfile
FROM blender:4.4.3
COPY blender_addon/bld_remote_mcp/ /opt/blender/scripts/addons/
ENV BLD_REMOTE_MCP_START_NOW=1
CMD ["blender", "--background", "--python", "/app/automation.py"]
```
### Development Installation
```bash
# Clone and install from source
git clone https://github.com/igamenovoer/blender-remote.git
cd blender-remote
pixi install # or pip install -e .
```
### CLI Tools (for testing)
```bash
# Check connection to BLD_Remote_MCP service
blender-remote status
# Execute Blender Python code
blender-remote exec "bpy.ops.mesh.primitive_cube_add()"
# Get scene information
blender-remote scene
# Capture viewport screenshot
blender-remote screenshot
```
### Python API (for custom scripts)
```python
# Direct connection to BLD_Remote_MCP service
import socket
import json
# Connect to service
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(('127.0.0.1', 6688))
# Send command
command = {"type": "execute_code", "params": {"code": "bpy.ops.mesh.primitive_cube_add()"}}
sock.sendall(json.dumps(command).encode('utf-8'))
# Get response
response = json.loads(sock.recv(4096).decode('utf-8'))
print(response)
sock.close()
```
## 🧪 Testing & Development
This project uses [pixi](https://pixi.sh) for environment management:
```bash
# Install pixi (if not already installed)
curl -fsSL https://pixi.sh/install.sh | bash
# Create development environment
pixi install
# Run comprehensive test suite
pixi run python tests/run_dual_service_tests.py
# Quick smoke test
pixi run python tests/smoke_test.py
# Test MCP server functionality
pixi run python tests/mcp-server/test_fastmcp_server.py
```
## 📁 Project Structure
```
blender-remote/
├── blender_addon/ # Blender add-ons
│ └── bld_remote_mcp/ # BLD_Remote_MCP service (port 6688)
├── src/blender_remote/ # Python package (src layout)
│ ├── mcp_server.py # FastMCP server implementation
│ └── cli.py # CLI tools
├── tests/ # Comprehensive test suite
│ ├── mcp-server/ # MCP server functionality tests
│ ├── integration/ # Service comparison tests
│ └── others/ # Development scripts
├── docs/ # Documentation
├── examples/ # Usage examples
└── context/ # AI assistant resources
```
## 🔧 Automation Capabilities
### Background Mode Support
**Key Advantage**: Full automation support in both GUI and headless environments:
- **GUI Mode**: Complete functionality including viewport screenshots
- **Background Mode**: Code execution, scene manipulation, rendering (no screenshots)
- **Automatic Detection**: Service gracefully handles mode-specific limitations
**Automation Patterns:**
```bash
# Interactive development with screenshots
export BLD_REMOTE_MCP_START_NOW=1
blender & # GUI mode with auto-start service
# Production automation (CI/CD, render farms)
blender --background --python start_service.py & # Headless with service
```
### External Control Examples
**Batch Asset Generation:**
```python
# automation_example.py
import socket, json, time
def send_blender_command(cmd_type, params={}):
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(('127.0.0.1', 6688))
command = {"type": cmd_type, "params": params}
sock.send(json.dumps(command).encode())
response = json.loads(sock.recv(4096).decode())
sock.close()
return response
# Automated workflow
send_blender_command("execute_code", {"code": "bpy.ops.object.select_all(action='DELETE')"})
send_blender_command("execute_code", {"code": "bpy.ops.mesh.primitive_cube_add(location=(0,0,0))"})
send_blender_command("execute_code", {"code": "bpy.context.object.name = 'AutoCube'"})
print("✅ Automated asset creation complete")
```
## 🔧 Troubleshooting
### Common Issues
**"Connection refused" error:**
- Ensure Blender is running with BLD_Remote_MCP addon enabled
- **Verify addon installation**: Check system console for registration messages:
```
✅ BLD Remote MCP addon registered successfully
✅ BLD Remote server STARTED successfully on port 6688
```
- Check service is listening: `netstat -tlnp | grep 6688`
- Try restarting Blender with environment variables set
**Add-on not working:**
- **Critical**: Check system console (Windows: `Window > Toggle System Console`, macOS/Linux: start from terminal)
- Look for registration messages when enabling the add-on
- If no messages appear, the add-on failed to load - check console for errors
**"No module named 'fastmcp'" error:**
- Install with uvx: `uvx blender-remote` (handles dependencies automatically)
- For development: `pixi run pip install fastmcp>=2.0.0`
**Screenshots not working:**
- Only available in GUI mode (`blender`, not `blender --background`)
- Service will return clear error message in background mode
### Debug Mode
```bash
# Test MCP server directly
pixi run python -m blender_remote.mcp_server
# Test with FastMCP inspector
pixi run fastmcp dev src/blender_remote/mcp_server.py
```
## 🤝 Contributing
Contributions are welcome! Please see our comprehensive test suite and development workflow:
1. **Fork the repository** and create a feature branch
2. **Run tests**: `pixi run python tests/run_dual_service_tests.py`
3. **Add tests** for new functionality
4. **Submit pull request** with clear description
## 📄 License
[MIT License](LICENSE)
## 🙏 Credits
This project was inspired by [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp), which demonstrated the potential for integrating Blender with the Model Context Protocol. We extend our gratitude to the original developers for pioneering this concept.
blender-remote builds upon this foundation with enhanced features including background mode support, thread-safe operations, comprehensive testing, and production-ready deployment capabilities.
## 🔗 Links
- **📚 Documentation**: [https://igamenovoer.github.io/blender-remote/](https://igamenovoer.github.io/blender-remote/)
- **🐛 Issue Tracker**: [Report bugs and request features](https://github.com/igamenovoer/blender-remote/issues)
- **💬 Discussions**: [Community support](https://github.com/igamenovoer/blender-remote/discussions)
- **🎥 Examples**: [Usage examples and workflows](https://github.com/igamenovoer/blender-remote/tree/main/examples)
---
**🎯 Ready to enhance your Blender workflow with AI? Start with `uvx blender-remote` today!**
Raw data
{
"_id": null,
"home_page": null,
"name": "blender-remote",
"maintainer": "blender-remote contributors",
"docs_url": null,
"requires_python": ">=3.10",
"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/c8/d9/08d1e4a26c500a69a9d764f8f45ccf5c661f0e8795abe89e0d69fdf38986/blender_remote-1.1.0.tar.gz",
"platform": null,
"description": "# blender-remote\n\n\ud83c\udfaf **Automate Blender workflows with external Python control, background operation, and LLM integration**\n\nblender-remote enables comprehensive Blender automation through multiple interfaces: auto-start service for external Python control, background mode operation for headless workflows, MCP server for LLM integration, and direct Python APIs. Perfect for CI/CD pipelines, render farms, and AI-assisted 3D workflows.\n\n## \u2728 Core Features\n\n### 1. **\ud83d\udd27 Auto-Start Service for Blender Automation**\nEnable headless Blender automation via external Python control:\n\n```bash\n# Set auto-start and launch Blender\nexport BLD_REMOTE_MCP_START_NOW=1\nblender &\n\n# External Python script controls Blender\npython automation_script.py # Connects to port 6688, executes Blender operations\n```\n\n**Perfect for**: CI/CD pipelines, batch processing, render farms, automated asset generation\n\n### 2. **\ud83d\udda5\ufe0f Background Mode Operation** \nRun Blender completely headless with `blender --background`:\n\n```python\n# start_blender_bg.py - Script to enable service in background mode\nimport bpy\nimport bld_remote\nbld_remote.start_mcp_service() # Starts service on port 6688\n```\n\n```bash\n# Launch headless Blender with service\nblender --background --python start_blender_bg.py &\n\n# External control works identically\npython your_automation.py # Same API, no GUI required\n```\n\n**Perfect for**: Headless servers, Docker containers, cloud rendering, automated workflows\n\n### 3. **\ud83e\udd16 MCP Server for LLM Integration**\nStandard Model Context Protocol server for AI assistant control:\n\n```bash\nuvx blender-remote # Starts MCP server for Claude, VSCode, Cursor, etc.\n```\n\n**Compatible with**: VSCode Claude, Claude Desktop, Cursor, and other MCP-compatible LLM IDEs\n\n### 4. **\ud83d\udc0d Python Control Classes**\nDirect Python API for programmatic Blender control *(coming soon)*\n\n**Enables**: Native Python integration, custom automation tools, scripted workflows\n\n## \ud83d\ude80 Quick Start\n\n### For Automation Users\n\n**Auto-Start Service Pattern:**\n```bash\n# 1. Install addon (see details below) and set auto-start\nexport BLD_REMOTE_MCP_START_NOW=1\nblender &\n\n# 2. External Python automation via socket connection\npython -c \"\nimport socket, json\nsock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\nsock.connect(('127.0.0.1', 6688))\ncmd = {'type': 'execute_code', 'params': {'code': 'bpy.ops.mesh.primitive_cube_add()'}}\nsock.send(json.dumps(cmd).encode())\nresponse = sock.recv(4096).decode()\nprint('Blender automated:', response)\nsock.close()\n\"\n```\n\n**Background Mode Pattern:**\n```bash\n# 1. Create service startup script\necho 'import bld_remote; bld_remote.start_mcp_service()' > start_bg_service.py\n\n# 2. Launch headless Blender with service\nblender --background --python start_bg_service.py &\n\n# 3. Same automation API works without GUI\npython your_automation_script.py\n```\n\n### For LLM Users\n\n### 1. Install Blender Add-on\n\n#### Create the Add-on Zip File\n\n```bash\n# Navigate to the blender_addon directory from project root\ncd blender-remote/ # Your cloned repository\ncd blender_addon/\nzip -r bld_remote_mcp.zip bld_remote_mcp/\n```\n\n**Note**: The `bld_remote_mcp.zip` file is not included in the repository and must be created by users from the `blender_addon/bld_remote_mcp/` directory.\n\n#### Install via Blender GUI (Recommended)\n\n1. **Open Blender**\n2. Go to `Edit > Preferences` from the top menu bar\n3. In the Preferences window, select the `Add-ons` tab\n4. Click the `Install...` button (opens Blender's file browser)\n5. Navigate to your `blender_addon/` directory and select `bld_remote_mcp.zip`\n6. Click `Install Add-on`\n7. **Search for \"BLD Remote MCP\" and enable it by ticking the checkbox**\n\n#### Alternative: Manual Installation\n\n```bash\n# Copy directly to Blender addons directory\nmkdir -p ~/.config/blender/4.4/scripts/addons/\ncp -r bld_remote_mcp/ ~/.config/blender/4.4/scripts/addons/\n```\n\n#### Verify Installation\n\n**Important**: This add-on has no visible GUI panel. Verify installation via system console:\n\n**Windows**: `Window > Toggle System Console` \n**macOS/Linux**: Start Blender from terminal\n\n**Look for these log messages when enabling the add-on:**\n```\n=== BLD REMOTE MCP ADDON REGISTRATION STARTING ===\n\ud83d\ude80 DEV-TEST-UPDATE: BLD Remote MCP v1.0.2 Loading!\n...\n\u2705 BLD Remote MCP addon registered successfully\n=== BLD REMOTE MCP ADDON REGISTRATION COMPLETED ===\n```\n\n**If auto-start is enabled, you'll also see:**\n```\n\u2705 Starting server on port 6688\n\u2705 BLD Remote server STARTED successfully on port 6688\nServer is now listening for connections on 127.0.0.1:6688\n```\n\n### 2. Start Blender with Auto-Service\n\n```bash\n# Set environment variables and start Blender\nexport BLD_REMOTE_MCP_PORT=6688\nexport BLD_REMOTE_MCP_START_NOW=1\nblender & # or \"blender --background\" for headless mode\n```\n\n### 3. Configure Your LLM IDE\n\n**VSCode (with Claude/Cursor extensions):**\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"blender-remote\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"blender-remote\"]\n }\n }\n }\n}\n```\n\n**Claude Desktop:**\n```json\n{\n \"mcpServers\": {\n \"blender-remote\": {\n \"command\": \"uvx\",\n \"args\": [\"blender-remote\"]\n }\n }\n}\n```\n\n### 4. Start Creating with AI! \ud83c\udf89\n\nYour LLM can now:\n- **Inspect scenes**: \"What objects are in the current Blender scene?\"\n- **Execute code**: \"Create a blue metallic cube at position (2, 0, 0)\"\n- **Take screenshots**: \"Show me the current viewport\"\n- **Automate workflows**: \"Create a donut tutorial scene with lighting\"\n\n## \ud83c\udfd7\ufe0f Architecture\n\n**Multi-Interface Design for Different Automation Needs:**\n\n```\nExternal Python Scripts \u2190\u2500\u2500\u2500\u2500\u2510\n \u2502\nLLM IDE (VSCode/Claude) \u2190\u2500\u2500\u2500\u2500\u253c\u2500\u2192 JSON-TCP (port 6688) \u2190\u2500 BLD_Remote_MCP (Blender addon)\n \u2502 \u2193\nblender-remote (uvx MCP) \u2190\u2500\u2500\u2500\u2518 Blender Python API\n \u2193\nPython Control Classes* \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2192 Blender (GUI or --background)\n```\n\n**Three Control Pathways:**\n1. **Direct Socket Connection**: External Python \u2192 JSON-TCP \u2192 Blender\n2. **MCP Protocol**: LLM IDE \u2192 uvx blender-remote \u2192 JSON-TCP \u2192 Blender \n3. **Python Classes**: Python \u2192 Direct API \u2192 Blender *(coming soon)*\n\n## \ud83d\udccb Available MCP Tools\n\n| Tool | Description | Example Use |\n|------|-------------|-------------|\n| `get_scene_info()` | List all objects, materials, and scene properties | Scene analysis |\n| `get_object_info(name)` | Get detailed object properties | Object inspection |\n| `execute_blender_code(code)` | Run Python code in Blender context | Any Blender operation |\n| `get_viewport_screenshot()` | Capture viewport as base64 image | Visual feedback |\n| `check_connection_status()` | Verify service health | Debugging |\n\n## \ud83d\udd27 Advanced Usage\n\n### Automation Integration\n\n**CI/CD Pipeline Example:**\n```yaml\n# .github/workflows/blender-automation.yml\n- name: Setup Blender Automation\n run: |\n export BLD_REMOTE_MCP_START_NOW=1\n blender --background --python setup_service.py &\n sleep 10 # Wait for service startup\n python batch_render_pipeline.py\n```\n\n**Docker Container:**\n```dockerfile\nFROM blender:4.4.3\nCOPY blender_addon/bld_remote_mcp/ /opt/blender/scripts/addons/\nENV BLD_REMOTE_MCP_START_NOW=1\nCMD [\"blender\", \"--background\", \"--python\", \"/app/automation.py\"]\n```\n\n### Development Installation\n\n```bash\n# Clone and install from source\ngit clone https://github.com/igamenovoer/blender-remote.git\ncd blender-remote\npixi install # or pip install -e .\n```\n\n### CLI Tools (for testing)\n\n```bash\n# Check connection to BLD_Remote_MCP service\nblender-remote status\n\n# Execute Blender Python code\nblender-remote exec \"bpy.ops.mesh.primitive_cube_add()\"\n\n# Get scene information\nblender-remote scene\n\n# Capture viewport screenshot\nblender-remote screenshot\n```\n\n### Python API (for custom scripts)\n\n```python\n# Direct connection to BLD_Remote_MCP service\nimport socket\nimport json\n\n# Connect to service\nsock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\nsock.connect(('127.0.0.1', 6688))\n\n# Send command\ncommand = {\"type\": \"execute_code\", \"params\": {\"code\": \"bpy.ops.mesh.primitive_cube_add()\"}}\nsock.sendall(json.dumps(command).encode('utf-8'))\n\n# Get response\nresponse = json.loads(sock.recv(4096).decode('utf-8'))\nprint(response)\nsock.close()\n```\n\n## \ud83e\uddea Testing & Development\n\nThis project uses [pixi](https://pixi.sh) for environment management:\n\n```bash\n# Install pixi (if not already installed)\ncurl -fsSL https://pixi.sh/install.sh | bash\n\n# Create development environment\npixi install\n\n# Run comprehensive test suite\npixi run python tests/run_dual_service_tests.py\n\n# Quick smoke test\npixi run python tests/smoke_test.py\n\n# Test MCP server functionality\npixi run python tests/mcp-server/test_fastmcp_server.py\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nblender-remote/\n\u251c\u2500\u2500 blender_addon/ # Blender add-ons\n\u2502 \u2514\u2500\u2500 bld_remote_mcp/ # BLD_Remote_MCP service (port 6688)\n\u251c\u2500\u2500 src/blender_remote/ # Python package (src layout)\n\u2502 \u251c\u2500\u2500 mcp_server.py # FastMCP server implementation\n\u2502 \u2514\u2500\u2500 cli.py # CLI tools\n\u251c\u2500\u2500 tests/ # Comprehensive test suite\n\u2502 \u251c\u2500\u2500 mcp-server/ # MCP server functionality tests\n\u2502 \u251c\u2500\u2500 integration/ # Service comparison tests\n\u2502 \u2514\u2500\u2500 others/ # Development scripts\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 examples/ # Usage examples\n\u2514\u2500\u2500 context/ # AI assistant resources\n```\n\n## \ud83d\udd27 Automation Capabilities\n\n### Background Mode Support\n\n**Key Advantage**: Full automation support in both GUI and headless environments:\n\n- **GUI Mode**: Complete functionality including viewport screenshots\n- **Background Mode**: Code execution, scene manipulation, rendering (no screenshots)\n- **Automatic Detection**: Service gracefully handles mode-specific limitations\n\n**Automation Patterns:**\n\n```bash\n# Interactive development with screenshots\nexport BLD_REMOTE_MCP_START_NOW=1\nblender & # GUI mode with auto-start service\n\n# Production automation (CI/CD, render farms)\nblender --background --python start_service.py & # Headless with service\n```\n\n### External Control Examples\n\n**Batch Asset Generation:**\n```python\n# automation_example.py\nimport socket, json, time\n\ndef send_blender_command(cmd_type, params={}):\n sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n sock.connect(('127.0.0.1', 6688))\n command = {\"type\": cmd_type, \"params\": params}\n sock.send(json.dumps(command).encode())\n response = json.loads(sock.recv(4096).decode())\n sock.close()\n return response\n\n# Automated workflow\nsend_blender_command(\"execute_code\", {\"code\": \"bpy.ops.object.select_all(action='DELETE')\"})\nsend_blender_command(\"execute_code\", {\"code\": \"bpy.ops.mesh.primitive_cube_add(location=(0,0,0))\"})\nsend_blender_command(\"execute_code\", {\"code\": \"bpy.context.object.name = 'AutoCube'\"})\nprint(\"\u2705 Automated asset creation complete\")\n```\n\n## \ud83d\udd27 Troubleshooting\n\n### Common Issues\n\n**\"Connection refused\" error:**\n- Ensure Blender is running with BLD_Remote_MCP addon enabled\n- **Verify addon installation**: Check system console for registration messages:\n ```\n \u2705 BLD Remote MCP addon registered successfully\n \u2705 BLD Remote server STARTED successfully on port 6688\n ```\n- Check service is listening: `netstat -tlnp | grep 6688`\n- Try restarting Blender with environment variables set\n\n**Add-on not working:**\n- **Critical**: Check system console (Windows: `Window > Toggle System Console`, macOS/Linux: start from terminal)\n- Look for registration messages when enabling the add-on\n- If no messages appear, the add-on failed to load - check console for errors\n\n**\"No module named 'fastmcp'\" error:**\n- Install with uvx: `uvx blender-remote` (handles dependencies automatically)\n- For development: `pixi run pip install fastmcp>=2.0.0`\n\n**Screenshots not working:**\n- Only available in GUI mode (`blender`, not `blender --background`)\n- Service will return clear error message in background mode\n\n### Debug Mode\n\n```bash\n# Test MCP server directly\npixi run python -m blender_remote.mcp_server\n\n# Test with FastMCP inspector\npixi run fastmcp dev src/blender_remote/mcp_server.py\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see our comprehensive test suite and development workflow:\n\n1. **Fork the repository** and create a feature branch\n2. **Run tests**: `pixi run python tests/run_dual_service_tests.py`\n3. **Add tests** for new functionality\n4. **Submit pull request** with clear description\n\n## \ud83d\udcc4 License\n\n[MIT License](LICENSE)\n\n## \ud83d\ude4f Credits\n\nThis project was inspired by [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp), which demonstrated the potential for integrating Blender with the Model Context Protocol. We extend our gratitude to the original developers for pioneering this concept.\n\nblender-remote builds upon this foundation with enhanced features including background mode support, thread-safe operations, comprehensive testing, and production-ready deployment capabilities.\n\n## \ud83d\udd17 Links\n\n- **\ud83d\udcda Documentation**: [https://igamenovoer.github.io/blender-remote/](https://igamenovoer.github.io/blender-remote/)\n- **\ud83d\udc1b Issue Tracker**: [Report bugs and request features](https://github.com/igamenovoer/blender-remote/issues)\n- **\ud83d\udcac Discussions**: [Community support](https://github.com/igamenovoer/blender-remote/discussions)\n- **\ud83c\udfa5 Examples**: [Usage examples and workflows](https://github.com/igamenovoer/blender-remote/tree/main/examples)\n\n---\n\n**\ud83c\udfaf Ready to enhance your Blender workflow with AI? Start with `uvx blender-remote` today!**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automate Blender workflows with external Python control, background operation, and LLM integration",
"version": "1.1.0",
"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": "b6dce4cdcf5d2b86ed04f0d11d9f4c0b68c46a3998afa32794ed77fccf627340",
"md5": "16c9c8592cf98158580007ca327bf7bb",
"sha256": "02cf411bb72eee9fb78e2fecae6074aece5df469b6ee7d9682220f4fdfdb840b"
},
"downloads": -1,
"filename": "blender_remote-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16c9c8592cf98158580007ca327bf7bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 30249,
"upload_time": "2025-07-09T11:35:39",
"upload_time_iso_8601": "2025-07-09T11:35:39.867688Z",
"url": "https://files.pythonhosted.org/packages/b6/dc/e4cdcf5d2b86ed04f0d11d9f4c0b68c46a3998afa32794ed77fccf627340/blender_remote-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c8d908d1e4a26c500a69a9d764f8f45ccf5c661f0e8795abe89e0d69fdf38986",
"md5": "939a8aa94725c194f1cd02adbb695332",
"sha256": "561e197b4a9d52c5dba10910e677b5cbc7649de55806985cae0b84841f097315"
},
"downloads": -1,
"filename": "blender_remote-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "939a8aa94725c194f1cd02adbb695332",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 69752,
"upload_time": "2025-07-09T11:35:41",
"upload_time_iso_8601": "2025-07-09T11:35:41.027629Z",
"url": "https://files.pythonhosted.org/packages/c8/d9/08d1e4a26c500a69a9d764f8f45ccf5c661f0e8795abe89e0d69fdf38986/blender_remote-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 11:35:41",
"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
