opensim-blender

opensim-blender is a containerized Blender runtime for the OpenSim AI stack.

Note, there is current no working arm64 build for this, docker contain is Intel only

It runs Blender with a virtual display (xvfb) and the Blender MCP add-on enabled.

The upstream add-on/server pair uses stdio + a local TCP bridge, not native MCP-over-HTTP. This image adds an mcp-proxy sidecar process in-container so upstream services can connect using HTTP (/mcp).

This is part of the opensim-stack and is intended to be used in conjunction with other parts of the stack. See Docs for full details.

What this image does

• Installs Blender and virtual display support
• Installs the Blender MCP add-on
• Starts Blender with the add-on TCP protocol server enabled (internal only)
• Runs blender-mcp (stdio MCP server) connected to that internal TCP server
• Exposes MCP over HTTP via mcp-proxy on container port 8996 (/mcp)
• Uses /workspace as the default project directory

Runtime defaults

• BLENDER_MCP_HOST=0.0.0.0
• BLENDER_MCP_PORT=8996
• BLENDER_TCP_PROTOCOL_HOST=127.0.0.1
• BLENDER_TCP_PROTOCOL_PORT=9876
• BLENDER_PROJECT_DIR=/workspace
• MCP HTTP listen endpoint: http://<container>:8996/mcp

Required volume mappings

• opensim-workspace -> /workspace
• blender-config -> /root/.config/blender
• blender-cache -> /root/.cache/blender
• blender-data -> /root/.local/share/blender

Build local image

docker build -t opensim-blender:local .

Run local image

docker run --rm \
  -e BLENDER_MCP_HOST=0.0.0.0 \
  -e BLENDER_MCP_PORT=8996 \
  -p 8996:8996 \
  -v opensim-workspace:/workspace \
  -v blender-config:/root/.config/blender \
  -v blender-cache:/root/.cache/blender \
  -v blender-data:/root/.local/share/blender \
  opensim-blender:local

Optional environment variables

• BLENDER_MCP_HOST MCP HTTP bind host (default 0.0.0.0)
• BLENDER_MCP_PORT MCP HTTP bind port (default 8996)
• BLENDER_TCP_PROTOCOL_HOST internal Blender add-on TCP host used by blender-mcp (default 127.0.0.1)
• BLENDER_TCP_PROTOCOL_PORT internal Blender add-on TCP port (default 9876)
• BLENDER_PROJECT_DIR override startup directory (default /workspace)
• BLENDER_EXTRA_ARGS extra flags appended to the Blender command

Compatibility notes:

• BLENDER_BRIDGE_HOST and BLENDER_BRIDGE_PORT are still accepted as legacy aliases.
• BLENDER_MCP_ENDPOINT is accepted for compatibility, but MCP HTTP is currently exposed at /mcp.

Build and publish multiarch image

Create/use a buildx builder once:

docker buildx create --name multiarch --use
docker buildx inspect --bootstrap

Build and push Linux AMD64 + ARM64:

docker buildx build \
  --platform linux/amd64 \
  -t bithatch/opensim-blender:latest \
  -t bithatch/opensim-blender:$(date +%Y%m%d) \
  --push \
  .

Project Links

• Main AI Stack (opensim-ai-docker): https://github.com/opensim-stack/opensim-ai-docker
• Blender MCP add-on: https://github.com/ahujasid/blender-mcp
• Related projects:
  • opensim-console2mcp: https://github.com/opensim-stack/opensim-console2mcp
  • opensim-metaverse2mcp: https://github.com/opensim-stack/opensim-metaverse2mcp
  • opensim-opencode: https://github.com/opensim-stack/opensim-opencode