Blender Product Studio Agent

A local, editable Blender product modeling and advertising photography workspace. The Blender tool layer is exposed through stdio MCP, so Claude Code, Codex, and other local MCP hosts can operate the same project. The included web UI is optional; its built-in chat uses Codex separately.

中文说明 · License · Security

What it does

• Keeps supplied photos, dimensions, SVGs, and references with the project.

• Makes a new .blend revision for every edit; records working and approved versions separately.

• Queues Blender work, keeps logs, and renders real PNGs from a frozen scene snapshot.

• Provides project, image inspection, editing, render, and asset publishing tools over MCP.

• Can publish a model collection at a stable library path for linked scene files.

It does not supply a hosted AI model, a cloud renderer, or an image generator. Blender runs locally. The bundled product studio skill contains the modeling and photography workflow.

Related MCP server: BlenderMCP

Install and start

Requirements: Node.js 22+, Blender installed locally, and enough disk space for .blend snapshots and renders. Development was done with Blender 5.2.1; check compatibility before relying on another version. A Codex login is needed only for the optional chat in the web UI.

git clone https://github.com/SanJoeng/blender-product-studio-agent.git
cd blender-product-studio-agent
npm ci
npm run build
npm start

Open http://127.0.0.1:4318. On macOS, Start.command also installs dependencies if needed, builds, and opens the local page. If Blender is not found, set BLENDER_PATH in .env using .env.example. The data directory is .studio/ by default and is excluded from Git. Back it up separately.

Use from Claude Code

Keep npm start running. In another terminal, register the local MCP adapter using the absolute path to your clone:

claude mcp add --transport stdio product-studio -- node /ABSOLUTE/PATH/blender-product-studio-agent/dist/mcp-external.js

Start Claude Code and ask it to call list_projects, then select_project or create_project. It should read SKILL.md through read_skill before modeling. For example:

Use product-studio MCP. Create a project for this 100 mm amber bottle, read the bundled skill, then model an editable bottle and make a small preview. Wait for the Blender jobs and inspect the preview image.

Claude Code's official MCP setup guide describes claude mcp add and project configuration. No Codex account is needed for this path. The Claude Code process and the studio server must run on the same computer.

Use from another AI harness

Configure a local stdio MCP server with:

{
  "command": "node",
  "args": ["/ABSOLUTE/PATH/blender-product-studio-agent/dist/mcp-external.js"]
}

Use the host's own MCP configuration format. Run the studio server first. The client controls its own model and login; this repository provides tools and workflow guidance. Typical sequence:

1. list_projects → select_project or create_project → get_project.

2. read_skill({"path":"SKILL.md"}) and the relevant reference guide. Use import_local_input for explicitly supplied photo/SVG paths, then view_image on their project previews. Use import_blend_path for an existing .blend.

3. edit_scene with Blender Python. It returns a job ID. Call get_job until completed.

4. render_scene from the exact revision ID, then get_job, then view_image on the returned preview path.

5. Use select_revision for rollback; use publish_asset when the reusable model should be updated for linked scenes. Long-running jobs can be stopped with cancel_job.

The MCP adapter selects one active project per client connection. Set STUDIO_PROJECT_ID in the adapter environment to preselect a known project; otherwise use the project tools. If the studio uses a custom data directory or port, pass the same STUDIO_DATA_DIR and STUDIO_URL=http://127.0.0.1:PORT to the adapter. Its local connection secret is generated in the data directory; do not copy it into public configuration files.

Architecture

Claude Code / another local MCP host ── stdio MCP ──┐
                                                      ├─ local studio server ── Blender CLI ── .blend / PNG
Web UI ── optional Codex chat ── scoped stdio MCP ────┘       │
                                                              └─ project files, versions, logs

The server binds only to 127.0.0.1. Its independent MCP adapter is a local process, not a public remote MCP URL. The studio serializes Blender jobs across clients. Completed images do not update automatically when a source model changes; new renders use the chosen revision.

Development

npm run check
npm test
npm run smoke

npm test exercises the independent MCP handshake and project tools without running Blender. npm run smoke runs a small real Blender edit and render. Model judgment still requires inspecting reference photos and previews.

License

GPL-3.0-only. The bundled skill has its own copy of the same license. User projects and uploaded product assets are stored outside the source tree and are not included in this repository.