远程混音器

Name: 远程混音器
Author: igamenovoer

作者：igamenovoer5 星标更新：2025-07-17

安装使用来源：spider==github.com

项目介绍

blender-remote

概述

目的：通过LLM辅助的Python开发实现复杂的Blender自动化，弥合AI生成的Blender脚本与外部Python工具之间的差距。

预期用户：

需要复杂Blender自动化但没有时间掌握Blender的Python API的开发者
不愿意在Blender的基本文本编辑器中编写Blender侧Python代码的用户
依赖LLM进行代码生成并希望自动化Blender任务的开发者

我们的解决方案：

允许LLM生成Blender侧的Python代码，并帮助将其封装到外部Python API中
提供后台模式执行以实现完全自动化和批处理
我们不试图将所有Blender Python API映射到Python或MCP——相反，我们提供基础设施让用户能够使用LLM辅助开发自己的Python工具来与Blender交互
最终结果：使用你的VSCode和你自己的Python控制Blender，不受Blender基本Python环境和编辑器的限制，轻松编写复杂的Blender自动化项目

系统架构：

BLD_Remote_MCP - 使用JSON-RPC与外部调用者通信的Blender插件
MCP服务器 - 将来自LLM IDE（如VSCode、Claude、Cursor）的MCP命令转发给Blender插件
Python客户端 - 直接控制Blender插件，绕过MCP服务器进行自动化脚本

系统架构

关键特性：

在LLM生成的Blender侧代码与外部Python API之间无缝衔接
同时支持LLM和Python客户端访问，具有平滑的代码过渡工作流程
LLM辅助的包装代码生成，用于将Blender脚本转换为Python API
支持后台模式以实现自动化和批处理
跨平台支持：Windows、Linux、macOS

注意：此代码主要由AI辅助编写。请自行承担风险使用。

使用方法

安装

安装包：

pip install blender-remote

安装uv（MCP服务器所需）：

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

基础使用

命令行方法

使用blender-remote-cli设置和管理Blender集成：

1. 初始化并安装插件：

# 自动检测Blender（Windows/macOS）或指定路径
blender-remote-cli init

# 自动安装插件（推荐）
blender-remote-cli install

手动安装说明：如果你希望手动安装插件或检查其源代码，可以先导出它：
blender-remote-cli export --content=addon -o ./exported_addon
这将在./exported_addon目录内创建一个名为bld_remote_mcp的目录。你可以将该目录压缩并通过Blender的编辑 > 首选项 > 插件安装。

2. 在Blender GUI中验证安装：

打开Blender → 编辑 → 首选项 → 插件
搜索“BLD Remote MCP” —— 应已启用

3. 配置服务设置（可选，在启动前）：

# 配置自定义端口（默认为6688）
blender-remote-cli config set mcp_service.default_port=7777

# 配置日志级别
blender-remote-cli config set mcp_service.log_level=DEBUG

# 查看当前配置
blender-remote-cli config get mcp_service.default_port

4. 启动带有服务的Blender：

# 带有服务的GUI模式
blender-remote-cli start

# 后台模式用于自动化
blender-remote-cli start --background

# 加载特定场景
blender-remote-cli start --scene=my_project.blend

5. 对正在运行的Blender执行命令：

# 直接执行Python代码
blender-remote-cli execute -c "import bpy; bpy.ops.mesh.primitive_cube_add(location=(2, 0, 0))"

# 使用自定义端口执行
blender-remote-cli execute -c 'import bpy; print(f"Blender {bpy.app.version_string}")' --port 7888

# 执行Python文件
blender-remote-cli execute my_script.py

# 复杂代码使用base64编码（建议用于多行代码）
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. 导出插件或脚本供手动使用：

# 导出插件源代码供检查或手动安装
blender-remote-cli export --content=addon -o ./exported_addon

# 导出保持活动的脚本供自定义后台启动
blender-remote-cli export --content=keep-alive.py -o .

MCP服务器方法

对于像VSCode、Claude Desktop或Cursor这样的LLM IDE：

1. 首先安装Blender插件（参见上述命令行方法）

2. 启动带有服务的Blender：

blender-remote-cli start

3. 配置你的LLM IDE：

VSCode settings.json：

{
  "mcpServers": {
    "blender-remote": {
      "command": "uvx",
      "args": ["blender-remote"]
    }
  }
}

自定义主机/端口配置：

{
  "mcpServers": {
    "blender-remote": {
      "command": "uvx", 
      "args": ["blender-remote", "--host", "127.0.0.1", "--port", "6688"]
    }
  }
}

4. 与LLM一起使用：

“当前Blender场景中有哪些对象？”
“在位置(2, 0, 0)处创建一个金属蓝色立方体”
“将当前场景导出为GLB格式”
“帮我创建一个Python函数来生成立方体网格”

Python客户端方法

用于直接的Python自动化脚本：

import blender_remote

# 连接到正在运行的Blender服务
client = blender_remote.connect_to_blender(port=6688)

# 直接执行Blender Python代码
result = client.execute_python("bpy.ops.mesh.primitive_cube_add(location=(2, 0, 0))")

# 使用场景管理器进行高级操作
scene_manager = blender_remote.create_scene_manager(client)
scene_manager.set_camera_location(location=(7, -7, 5), target=(0, 0, 0))

# 获取场景信息
scene_info = client.get_scene_info()
print(f"场景包含 {len(scene_info['objects'])} 个对象")

高级使用

使用LLM开发Blender的Python工具

示例工作流程：

询问LLM：“生成一个立方体螺旋的Blender代码”
LLM生成：使用bpy操作的Blender侧Python代码
在Blender中测试：使用MCP工具执行并优化代码
询问LLM：“将其封装成我可以从外部脚本调用的Python函数”
LLM创建包装器：

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)

# 使用包装器
client = blender_remote.connect_to_blender()
create_cube_spiral(client, count=15, radius=5)

使用后台模式进行批处理

为了完全控制后台进程，你可以导出保持活动的脚本，如有需要修改它，并直接使用Blender运行。这对于自定义启动逻辑或集成到更大的自动化框架中非常有用。

1. 导出保持活动的脚本

blender-remote-cli export --content=keep-alive.py -o .

2. 使用脚本和所需的环境变量启动Blender

插件需要环境变量来知道使用哪个端口以及是否自动启动。

在Linux/macOS上：

# 设置环境变量并以后台模式启动Blender
export BLD_REMOTE_MCP_PORT=7788
export BLD_REMOTE_MCP_START_NOW=1
export BLD_REMOTE_LOG_LEVEL=DEBUG # 可选：详细日志
blender --background --python keep-alive.py &

在Windows（命令提示符）上：

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

在Windows（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

Python客户端随后可以连接到指定端口的手动启动实例。

自动化批处理工作流（使用CLI启动）：

import blender_remote
import subprocess
import time
import os

# 使用CLI启动后台Blender进程（避免路径问题）
port = 7888
process = subprocess.Popen([
    "python", "-m", "blender_remote.cli", "start", "--background", "--port", str(port)
])

# 等待服务启动
time.sleep(3)

# 连接到后台实例
client = blender_remote.connect_to_blender(port=port)

# 处理多个场景文件
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"处理 {scene_file}...")
    
    # 加载场景
    client.execute_python(f'bpy.ops.wm.open_mainfile(filepath="{scene_path_abs.replace(os.sep, "/")}")')
    
    # 处理场景（你的自定义操作）
    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))")
    
    # 导出结果
    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"导出 {output_file}")

# 平稳退出Blender
client.execute_python("bpy.ops.wm.quit_blender()")
process.wait()  # 等待进程完全退出

文档

完整文档：https://igamenovoer.github.io/blender-remote/
示例：examples/
问题报告：报告错误

致谢

基于blender-mcp项目，增强了后台模式支持、线程安全操作及生产部署能力。

许可证

MIT许可证