blender-remote 1.0.0

Remote control Blender with Python and MCP server

blender-remote

🎯 Control Blender from any LLM-powered IDE with zero configuration

blender-remote is a production-ready MCP (Model Context Protocol) server that enables AI coding assistants to control Blender remotely. Simply run uvx blender-remote and your LLM can inspect scenes, execute Python code, and capture screenshots directly from Blender.

✨ Key Features

• 🚀 Zero Installation: Run uvx blender-remote - no pip install needed
• 🤖 LLM Integration: Works with VSCode Claude, Cursor, and other MCP-compatible IDEs
• 📱 GUI + Background Mode: Unique support for both interactive and headless Blender
• 🔧 Complete Blender Control: Execute any Blender Python API code through your AI assistant
• 📸 Screenshot Capture: Get viewport images as base64 data for LLM analysis
• 🔄 Thread-Safe: Handles concurrent requests with UUID-based file management
• ⚡ Production Ready: Built on thoroughly tested BLD_Remote_MCP service

🎯 Quick Start for LLM Users

1. Install Blender Add-on

# Download and install the BLD_Remote_MCP addon
cd ~/.config/blender/4.4/scripts/addons/
wget -O bld_remote_mcp.zip https://github.com/igamenovoer/blender-remote/raw/main/blender_addon/bld_remote_mcp.zip
unzip bld_remote_mcp.zip

2. Start Blender with Auto-Service

# 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):

{
  "mcp": {
    "servers": {
      "blender-remote": {
        "type": "stdio",
        "command": "uvx",
        "args": ["blender-remote"]
      }
    }
  }
}

Claude Desktop:

{
  "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

LLM IDE (VSCode/Claude) 
    ↓ MCP Protocol
blender-remote (uvx)
    ↓ JSON-TCP (port 6688)
BLD_Remote_MCP (Blender addon)
    ↓ Python API
Blender (GUI or --background)

📋 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

Manual Installation (for development)

# 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)

# 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)

# 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 for environment management:

# 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

⚠️ Background Mode Support

Unique Advantage: Unlike other Blender MCP solutions, blender-remote supports both GUI and background modes:

• GUI Mode: Full functionality including viewport screenshots
• Background Mode: Code execution and scene inspection (screenshots unavailable)
• Automatic Detection: Service gracefully handles mode limitations

# GUI mode (recommended for development)
blender &

# Background mode (for servers/CI)
blender --background &

🔧 Troubleshooting

Common Issues

"Connection refused" error:

• Ensure Blender is running with BLD_Remote_MCP addon enabled
• Check service is listening: netstat -tlnp | grep 6688
• Try restarting Blender with environment variables set

"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

# 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

🔗 Links

• 📚 Documentation: https://igamenovoer.github.io/blender-remote/
• 🐛 Issue Tracker: Report bugs and request features
• 💬 Discussions: Community support
• 🎥 Examples: Usage examples and workflows

---

🎯 Ready to enhance your Blender workflow with AI? Start with uvx blender-remote today!