blender-remote


Nameblender-remote JSON
Version 1.1.0 PyPI version JSON
download
home_pageNone
SummaryAutomate Blender workflows with external Python control, background operation, and LLM integration
upload_time2025-07-09 11:35:41
maintainerblender-remote contributors
docs_urlNone
authorblender-remote contributors
requires_python>=3.10
licenseMIT
keywords blender remote-control 3d automation mcp api
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.43983s