scenemodel

scenemodel

scenemodel 是一个小型 MCP 服务和命令行工具，可通过 Agent 驱动 Blender 场景。它以洁净室方式重建了 ahujasid/blender-mcp 文档中核心功能的子集——共八个工具——包括场景和对象信息、任意 Blender Python 代码执行、视口截图、PolyHaven 分类浏览、搜索与下载，以及 Hunyuan3D 模型生成。

传输方式与原项目完全相同，未作改动：Blender 运行一个监听 TCP 套接字的插件（默认地址为 localhost:9876），并交换格式为 {type, params} 的 JSON 命令和 JSON 响应。scenemodel 在可注入的套接字函数后实现了完全相同的协议——每次调用建立一个连接、发送一个 JSON 请求、接收一个 JSON 响应——主机和端口由 BLENDER_HOST / BLENDER_PORT 指定。如果没有服务在监听，调用会如实返回底层连接错误（ECONNREFUSED）；scenemodel 不会编造场景数据。

有一处已知差异：上游的截图工具会返回图像内容。scenemodel 则返回工件摘要，包括图像格式、字节长度和 base64 长度，而不会返回图像内容块本身。

刻意省略的功能：Hyper3D（Rodin）生成工具及其状态检查、Hunyuan 任务状态／轮询（生成调用除外）、专用的 set_texture 工具（与原项目一样，仍可通过资源下载和代码执行设置纹理）、遥测／用户 ID 工具，以及 execute_blender_code 之外的视口场景操作。

发布的容器镜像不包含 Blender 二进制文件：插件运行在用户自己的 Blender 安装中，因此镜像需要连接到主机上的 Blender 套接字，并在 Dockerfile 中明确说明了这一点。

安装

npx @reneturcios/scenemodel get-scene-info
docker run -i ghcr.io/cloudcorprecords/scenemodel

请先启动 Blender 并启用 blender-mcp 插件；它默认监听 localhost:9876。

命令行

scenemodel get-scene-info
scenemodel get-object-info <object_name>
scenemodel execute-blender-code "import bpy; print(bpy.context.scene.name)"
scenemodel get-viewport-screenshot [--max-size 1024]
scenemodel get-polyhaven-categories [asset_type]
scenemodel search-polyhaven-assets [asset_type] [categories]
scenemodel download-polyhaven-asset <asset_id> <asset_type> [--resolution 2k] [--format gltf]
scenemodel generate-hunyuan3d-model --text "a wooden chair"
scenemodel --version

退出代码：0 表示成功，1 表示插件／套接字错误，2 表示用法错误。

MCP 服务

npx -y @reneturcios/scenemodel mcp

{
  "mcpServers": {
    "scenemodel": {
      "command": "npx",
      "args": ["-y", "@reneturcios/scenemodel", "mcp"],
      "env": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" }
    }
  }
}

env 块为可选项；此处显示的是默认值。

工具

工具	输入	插件命令
get_scene_info	—	get_scene_info
get_object_info	object_name（必填）	get_object_info
execute_blender_code	code（必填）	execute_code
get_viewport_screenshot	max_size（可选）	get_viewport_screenshot — 返回格式／长度摘要，而非图像内容
get_polyhaven_categories	asset_type（可选）	get_polyhaven_categories
search_polyhaven_assets	asset_type、categories（可选）	search_polyhaven_assets
download_polyhaven_asset	asset_id、asset_type（必填）、resolution、file_format	download_polyhaven_asset
generate_hunyuan3d_model	text_prompt、input_image_url（二者必填其一）	generate_hunyuan3d_model

插件错误封装和套接字故障——例如连接被拒绝、超时或响应格式错误——都会作为工具错误报告，并包含底层错误消息。

开发

npm install
npm run build
npm test
npm run dev

测试完全通过伪造的套接字函数运行，覆盖命令构造、响应解包、截图摘要和错误传播。测试不会连接到运行中的 Blender 实例。

许可证

MIT — 参见 LICENSE。