Blender MCP container

Container packaging for the official Blender Lab MCP server. The image runs the upstream entrypoint unchanged:

blender-mcp --transport http --host 0.0.0.0 --port 8000

The server uses Streamable HTTP at /. All 26 upstream tools are available. There is no custom HTTP application, authentication, tool filtering, or health API. Access control belongs at the gateway; this image is intended for an internal endpoint.

Runtime

The image uses the pinned LinuxServer Blender 5.2.2 image and the official MCP v1.0.3 source commit. pyproject.toml pins the official Git source; uv.lock records the resolved runtime and development dependencies for Python 3.14. The image uses uv 0.12.17 and uv sync --locked --no-dev --no-editable at build time. Ruff and uv are not installed in the final runtime image.

The LinuxServer desktop entrypoint is replaced with blender-mcp, so this container only starts the MCP server. The included Blender executable supports the six upstream _for_cli tools, which launch separate background Blender processes. Connected-session tools use BLENDER_MCP_HOST and BLENDER_MCP_PORT (defaults: 127.0.0.1:9876) to reach the addon in the authoring container.

Mount the same /workspace in both containers so CLI tools can open saved scenes, resolve assets, and exchange temporary copies of unsaved scenes. The chart gives the sidecar a writable /tmp and runs it as UID/GID 1000 with a read-only root filesystem. It does not request a second GPU: background CLI execution uses CPU, while connected tools execute inside the GPU-enabled authoring container.

Kubernetes TCP startup/readiness probes check port 8000. They do not prove that the addon is connected or Blender is responsive. Keep one active scene writer.

Related MCP server: blender-mcp

Development

Use uv 0.12.17 or newer. .python-version selects Python 3.14.

uv sync --locked
uv run --locked ruff check .
uv run --locked ruff format --check .

Ruff 0.16.8 enables all stable lint rules, including type annotations and import sorting. Exceptions cover formatter conflicts, optional copyright headers, and smoke-test conventions: no mandatory docstrings/package marker, assertions, fixed subprocess commands, and console output. Run uv lock --check and the local lint and formatting commands before publishing changes.

Upgrade dependencies with uv lock --upgrade, then rerun lint and the container smoke test. This resolves the newest versions allowed by upstream constraints. Blender MCP 1.0.3 requires mcp<2, so the lock currently selects SDK 1.30.0 even though SDK 2.x exists. Upgrade the official server and matching addon together before changing that compatibility boundary. The upstream setuptools build backend is constrained separately in tool.uv.build-constraint-dependencies.

Build and test

docker build -t blender-mcp:local .
docker run --rm --read-only --tmpfs /tmp:uid=1000,gid=1000 \
  --cap-drop=ALL --security-opt=no-new-privileges \
  --mount type=bind,src="$PWD/tests",dst=/tests,readonly \
  --entrypoint /opt/mcp/bin/python blender-mcp:local /tests/smoke.py

The smoke test initializes a real HTTP MCP client, lists all 26 tools, and executes a background Blender tool against a disposable scene without a running addon. Run this smoke test locally before publishing.

CI calls the shared build-push-container workflow to build, scan, and publish the image. The tags input in .github/workflows/build.yaml owns the image tag, currently 1.0.3-blender5.2.2-1. GitHub Actions publishes ghcr.io/a-homelab/blender-mcp on main or manual dispatch; pull requests build and scan without publishing. Ruff and the HTTP/CLI smoke test run locally. The Git remote is git@github.com:a-homelab/blender-mcp.git. Allow the cluster to pull the package before deploying it.

The deployment chart lives separately in a-homelab/helm-charts/charts/blender. Update its sidecar image tag when publishing a new version. Upgrade the source commit, addon version/checksum in the chart, and Blender image together.

Verification on 2026-09-18

After conversion to uv, lockfile freshness, strict Ruff linting, and formatting checks passed. The image built using uv sync --locked --no-dev --no-editable and passed the HTTP/CLI smoke test with all 26 tools. Its runtime contains MCP SDK 1.30.0 and excludes uv and Ruff executables. Build/test logs for this check are under /tmp/blender-mcp-uv/ on the validation machine.

The image built and passed the HTTP/CLI smoke test with a read-only root filesystem and no extra container capabilities. An isolated Blender desktop and MCP sidecar then initialized over HTTP, listed 26 tools, saved a disposable scene and GLB, read the shared scene through a CLI tool, and reopened it after both containers restarted without external network access. Temporary containers were removed. Raw evidence is under /tmp/blender-mcp-simplify/ on the validation machine.

No image was published and no cluster deployment changed. Package publication remains a prerequisite for deployment.