Blender MCP renderer

This image runs a Streamable HTTP MCP server from a Python virtual environment and launches a separate Blender 5.2 background process for each render. It exposes get_gpu_info and an asynchronous render-job API at http://localhost:8080/mcp.

The image also includes Tailscale. Set TAILSCALE_AUTH_KEY at runtime to join your tailnet as blender-render-mcp. Tailscale runs in userspace mode and forwards incoming tailnet connections to the same port on 127.0.0.1, so clients on the tailnet can use http://blender-render-mcp:8080/mcp (or the assigned name, such as blender-render-mcp-1). The MCP server keeps running if Tailscale cannot connect; check the container logs and restart it after fixing the connection. Userspace mode needs no TUN device or extra container privileges. Compose persists its login state in the tailscale-state volume; mount /home/headless/.local/share/tailscale on other platforms if you want the node identity to survive container replacement. Keep the auth key in a runtime environment variable, not a Docker build argument. See Tailscale's Linux install and userspace networking behavior.

To access the container shell over your tailnet, set TAILSCALE_SSH=true and allow SSH in your tailnet access policy. Connect as the container's local user, for example ssh headless@blender-render-mcp; a RunPod SSH routing name is not a Linux username in the container. Tailscale SSH does not require a separate sshd process. If Tailscale assigns a suffix such as blender-render-mcp-1, use that name until you remove the old offline node from your tailnet.

Start

CPU-only:

docker compose up --build -d

On an NVIDIA Docker host with the NVIDIA Container Toolkit configured:

docker compose -f compose.yaml -f compose.gpu.yaml up --build -d

The GPU override is optional. Without GPU passthrough, Cycles uses CPU. Eevee and Workbench are reported as unavailable and render requests for them return an error. On a GPU host, the service detects GPUs visible inside the container; Cycles selects OptiX when Blender reports an OptiX device and otherwise falls back to CPU.

To build and publish the RunPod image as gongfan99/blender-render-mcp:latest, first authenticate with Docker Hub using docker login, then run deploy.bat from Windows.

The local Compose port mapping binds only to 127.0.0.1. For RunPod, provide TAILSCALE_AUTH_KEY as a container environment variable to make the MCP endpoint available to permitted devices on your tailnet. The MCP server has no application-level authentication, so do not configure RunPod to expose port 8080 publicly.

Related MCP server: Blender MCP

Tools

get_gpu_info reports NVIDIA devices visible through nvidia-smi, Blender's version and OptiX detection, its OpenGL renderer, FFmpeg support, and engine availability. Eevee and Workbench require both a visible NVIDIA GPU and a hardware OpenGL context; software renderers such as llvmpipe do not count.

Rendering uses asynchronous jobs. submit_render_job queues an H.264 animation, while submit_frame_render_job queues selected still frames as PNG files in a ZIP archive. Both return a job ID without waiting for Blender. Use get_render_job_status to poll either job; it returns queued, running, completed, or failed, elapsed and running time, processed and total frame counts, and any error. Download completed animation jobs with download_render_result and frame jobs with download_render_frames.

submit_render_job accepts:

The submit response includes job_id, status_tool, and download_tool. Check get_render_job_status with that ID until the job finishes. processed_frames and total_frames are available after Blender opens the project and reports its frame range; total_frames can initially be null when the saved range is used. The server runs one Blender render at a time; additional jobs remain queued. Up to four jobs may be queued or running by default.

submit_frame_render_job accepts the same engine, resolution, and sample overrides as submit_render_job, plus a required frames list. The list must contain 1–100 unique integer frame numbers within the scene's saved frame range. The worker renders each requested frame once, preserves the scene's output resolution unless overridden, and returns numbered PNGs (for example, frame_000024.png) in rendered_frames.zip. The ZIP archive is capped at 250 MiB. Use the returned download_tool after status becomes completed to retrieve it as an embedded application/zip resource.

MCP call sequence:

submit_render_job({"blend_file_base64": "...", "engine": "cycles"})
get_render_job_status({"job_id": "<returned id>"})
download_render_result({"job_id": "<returned id>"})

For selected still frames:

submit_frame_render_job({"blend_file_base64": "...", "frames": [1, 24, 48], "engine": "eevee"})
get_render_job_status({"job_id": "<returned id>"})
download_render_frames({"job_id": "<returned id>"})

Animation MP4s use H.264 and are capped at 250 MiB; selected-frame PNG archives are also capped at 250 MiB. A job may render the saved animation frame range, so keep the range and output dimensions reasonable. Pack external textures and other assets into the .blend file before uploading; only the .blend bytes are sent. Blender's automatic Python execution is disabled for uploaded projects.

Jobs and results are held on the server's local filesystem for 24 hours by default. They are process-local and are lost if the container restarts; use one server instance for submit, status polling, and download.

Blender keeps the scene's saved engine, frame range, resolution, and samples unless the request overrides them. The worker selects the Cycles device and output path and format. Animation jobs use MPEG-4/H.264; selected-frame jobs save PNG images and package them in a ZIP archive. For Workbench, a sample override selects the closest supported value.

Configuration

The decoded .blend input limit is fixed at 100 MiB; MP4 and PNG ZIP outputs are each limited to 250 MiB, and frame-list jobs accept at most 100 frames. Only one Blender render runs at a time in each container.

Smoke tests

Run the unit tests with Python 3.10 or later after installing requirements.txt:

python -m unittest discover -s tests -v

For a live CPU-only test, create a tiny sample file with Blender in the image, then run the MCP client smoke test. It checks that Eevee and Workbench jobs fail clearly without a GPU and that Cycles returns a valid embedded MP4:

docker run --rm --entrypoint /home/headless/blender/blender -v "${PWD}:/workspace" -w /workspace blender-render-mcp:local --background --python tests/create_sample_blend.py -- /workspace/tests/cpu_sample.blend
python tests/smoke_mcp.py --blend tests/cpu_sample.blend --check-cpu-denials --frame 1

On an NVIDIA host, start Compose with compose.gpu.yaml and run python tests/smoke_mcp.py --blend tests/cpu_sample.blend --check-gpu-engines to render through Cycles, Eevee, and Workbench. Add --frame 1 to also verify a selected-frame PNG ZIP render; the requested frame must be within the blend's saved frame range.