Skip to main content
Glama

Remote Blender MCP

Control Blender on Modal from Codex, Claude Code, OpenCode, or another MCP client. The local Python server manages remote compute and transfers files. Blender runs remotely in a persistent process with full bpy access.

Setup

The local prototype supports macOS and Linux.

Install uv and authenticate with Modal:

uv sync --locked
uv run modal setup

Install the Codex configuration for this checkout:

uv run python scripts/setup_codex.py

This writes only the project's .codex/config.toml. It preserves other settings, uses the installed uv path, and forwards the optional Modal/profile and session-registry environment variables. Run it again after moving the checkout. Start a new Codex session in this trusted project to load the MCP. The configuration approves this server's tools, including arbitrary remote Python. Remove default_tools_approval_mode if you want Codex to ask before calls.

The generated entry has this form:

[mcp_servers.remote_blender]
command = "uv"
args = ["run", "--locked", "--directory", "/absolute/path/remote-blender-mcp", "remote-blender-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 600
default_tools_approval_mode = "approve"

The first session builds a Blender image and can take several minutes. Provisioning has a 180-second deadline, followed by a bounded worker-readiness check. A stalled allocation is cancelled only when its ownership tag matches the request. Different projects provision independently. The longer Codex tool timeout accommodates startup. Renders and Python operations return job IDs promptly. Use job_status to retrieve their results.

For clients that use JSON configuration:

{
  "mcpServers": {
    "remote_blender": {
      "command": "uv",
      "args": ["run", "--locked", "--directory", "/absolute/path/remote-blender-mcp", "remote-blender-mcp"]
    }
  }
}

Use an absolute path to uv if the client cannot find it. The server uses your existing Modal profile; it does not copy Modal credentials into Blender. Client configuration and image rendering behavior must be checked in the client you use.

Related MCP server: blender-server-mcp-docker

Compute selection

CPU is the default for modeling, rigging, animation editing, scene setup, nodes, routine inspection and small test renders. Codex should consider a GPU only for planned heavy animation rendering or expensive final renders when the supported backend and expected time/cost justify it. Being a 3D task, using GUI mode or spawning multiple agents is not enough to justify a GPU.

Use the Codex CPU/GPU decision matrix. Codex makes this choice per item and stage, records a short rationale, and stops GPU compute when the justified render stage ends. Allocation and render-device selection are separate: reserving a GPU does not automatically make Blender use it. No workload classifier or GPU-use restriction is implemented in the MCP.

First workflow

  1. Call create_session with a project name such as demo. Use mode="gui" for viewport control or mode="headless" for batch work. The default uses CPU and headless mode. Leave gpu unset for CPU; choose a supported GPU only when the decision matrix justifies the planned render stage. GPU availability depends on your Modal account and capacity.

  2. Call inspect_scene with the returned session_id.

  3. Call execute_python, then job_status until the job succeeds or fails. Assign a JSON-serializable value to result to return data.

  4. Call render, then inspect its job. Call view_image with the resulting relative PNG path for inline visual feedback.

  5. Call save_project with a new path such as exports/scene.blend, wait for success, and use download_file to retrieve it.

  6. Call stop_session to save the scene and terminate compute. Saved project data remains in its Modal Volume.

Example Blender code:

import bpy

bpy.ops.mesh.primitive_uv_sphere_add(location=(2, 0, 1))
sphere = bpy.context.object
sphere.name = "MySphere"
material = bpy.data.materials.new("Blue")
material.diffuse_color = (0.02, 0.15, 0.8, 1.0)
sphere.data.materials.append(material)
result = {"name": sphere.name, "objects": len(bpy.data.objects)}

A fresh project includes Blender's default cube, camera and light. render uses Cycles and the scene's camera. Set device="CUDA" or "OPTIX" for a GPU session; unavailable devices produce an error instead of silent CPU fallback. Specialized modeling, geometry nodes, materials, animation, rigging, simulation, import/export and add-on inspection are available through Python, subject to the pinned Blender build and background context.

Remote viewport

Create a session with mode="gui". The sandbox runs the official Blender 4.5.0 application on a private 1280 × 800 virtual display. control_viewport selects objects, frames selection, changes axis views, orbits with XYZ angles, pans with a target point, zooms with distance, changes shading and sets the timeline frame. Auto-framing evaluates the requested animation frame before calculating bounds. It checks selected bounding-box corners and armature endpoints against the real viewport region and adds a screen-space margin. Explicit target or distance values override auto-framing and can intentionally crop the view. viewport_screenshot returns the actual desktop framebuffer as an inline image, including Blender's viewport, selection, overlays and editors. Poll a pending screenshot job and retrieve its PNG with view_image.

Example Codex request:

Create a GUI session named my-blender-project. Add a sphere, select it, frame it in an isometric solid view, and show the viewport screenshot. Then switch to wireframe and inspect the result. Keep the project checkpointed.

The viewport uses Mesa software OpenGL on the remote CPU. This avoids requiring a local graphics context and does not claim hardware-accelerated viewport drawing. A GPU session can still use CUDA/OptiX for Cycles camera rendering. GUI commands run on Blender's main thread between UI redraws. The screenshot is a tool-requested image of the live GUI; no desktop video stream or mouse/keyboard forwarding is exposed.

Tools

Tools

Purpose

create_session, list_sessions, session_status, stop_session

Manage remote compute and reconnect using the local registry.

execute_python, run_operator

Full Python access or structured operator execution, including modeling, import/export and baking.

inspect_scene, inspect_object

Scene transforms, mesh counts, modifiers, materials, constraints, rig and animation action.

inspect_nodes

Shader, Geometry Nodes, world and compositor graphs, sockets and links.

describe_api

Search installed operators and inspect actual RNA schemas, enums and defaults.

get_environment, get_logs, inspect_dependencies

Discover runtime capabilities, diagnose errors and check asset references.

control_viewport, viewport_screenshot

Control and inspect the actual remote GUI viewport. Requires GUI mode.

render, view_image

Create camera renders and return inline PNG images.

job_status, cancel_job

Retrieve results, tracebacks and logs; stop queued or running work.

save_project, open_project

Save checkpoints, export a .blend, or open an uploaded project.

list_checkpoints, restore_checkpoint

List and restore saved scene revisions.

upload_file, download_file, list_files

Transfer files with checksum verification and explicit relative paths.

State and recovery

Each workspace uses its own named Modal Volume mounted at /workspace. The default workspace is addressed by project name. new_workspace=true creates an independent workspace even when another session has the same project label. Internal jobs and checkpoints live in /workspace/.rbm. Assets and exports use ordinary project paths. Transfers reject existing destination files. Upload dependencies explicitly; packing images does not include every possible dependency.

Successful Python operations save checkpoints by default. Set checkpoint=false for inspection or temporary edits. The Python namespace is new on each call; Blender scene data persists. Python errors can leave partial edits. Cancellation of a running job or a job deadline kills Blender and restores the last completed checkpoint. Queued work is failed after a worker restart so it cannot silently execute against an older scene. Inspect the restored state before resubmitting it. Job status records that unsaved changes were lost. Restoring a checkpoint or opening a project replaces the live scene.

The supervisor saves and stops after the configured user-idle period (15 minutes by default), once queued work is complete. Session status queries count as activity; job polling does not. An active job has a separate deadline. The default maximum session lifetime is one hour. A hard lifetime expiry or host failure can lose changes since the last completed checkpoint.

stop_session places a barrier after already accepted jobs and rejects later jobs while draining. If the final save is pending after approximately 30 seconds, it returns stopped:false, draining:true and the save job ID. Poll that job, then retry stopping; the retry reuses the same save. Failed saves reopen submission so the scene can be repaired. discard_unsaved=true provides emergency termination and loses unsaved edits. For a default workspace, create another session with the same project name to load the last checkpoint after termination. For an independent workspace, supply its returned workspace_id when reopening it. session_status and list_checkpoints also work after compute ends. If the latest checkpoint is unusable, create a session with restore_revision set to an older checkpoint ID. New checkpoints include checksum manifests; startup refuses a checksum mismatch. One named sandbox per workspace prevents duplicate attachment to that workspace in the same Modal App; independent workspaces may run concurrently under one project label. Changing the GPU profile or switching between headless and GUI modes requires stopping the current session first.

Local session records live in ~/.local/state/remote-blender-mcp; set RBM_STATE_DIR to change that location. Set RBM_MODAL_APP to change the default Modal App name. Default Volumes use rbm-<project> names; independent Volumes use rbm-i_<workspace UUID hex>. Both retain data after compute stops. Delete retained data only through an explicit storage-management action.

Prototype scope

The headless image uses Python 3.11 and bpy==4.5.0. GUI mode adds the official Blender 4.5.0 Linux archive, verified against its published SHA-256, and Xvfb. The lockfile pins the local dependency versions. Operations are serialized within each session, including renders. The prototype provides headless scene control, camera renders and live GUI viewport control with screenshots. Remote desktop input/video streaming, independent render workers, automatic dependency synchronization and asset-provider integrations are future work.

Arbitrary Python can access the remote OS and the project's mounted data. It is intended for a trusted local harness. The sandbox has no public port (X11 TCP listening is disabled), no injected user secrets, and outbound networking is disabled. Assets and add-ons that require network downloads must be staged explicitly or added to the image. Local upload/download tools have access to paths supplied by the harness. Do not expose the stdio server as an unauthenticated shared service.

CPU sessions request one physical core and 2 GiB RAM, with limits of four physical cores and 8 GiB RAM. GPU sessions also reserve the selected GPU. Modal charges for running resources; terminate sessions when finished. Checkpoint and artifact storage persists separately.

Validation

uv run pytest -q
uv run ruff check .

The live acceptance script starts billable Modal resources and stops its session when finished:

uv run python scripts/validate_live.py
RBM_TEST_GPU=L4 uv run python scripts/validate_live.py

It writes artifacts and a report under .validation/. See prototype validation for observed results and limits, and research and design for source research.

Actual Codex and GUI acceptance tests use an existing GUI session that you own:

uv run python scripts/validate_codex.py <session_id>
uv run python scripts/validate_viewport.py <session_id>

The Codex script uses your existing Codex login through a temporary authentication reference and an isolated configuration containing project trust. It loads this project's MCP entry and records real tool calls and model image inspection. It does not load home-level MCP servers or plugins. Both scripts leave the supplied session running; stop it with stop_session when finished.

Command coverage and debugging

There are 26 MCP tools. Use get_environment to identify the actual Blender build, enabled add-ons, devices and GUI mode. Search describe_api for the installed operator before invoking it through run_operator. For example, search export, inspect export_scene.gltf, create a workspace export directory through Python, then run the operator with the discovered arguments. CURRENT and VIEW_3D execution contexts are supported. An operator must report FINISHED; a failed poll or cancelled operator becomes an explicit failed job.

For work beyond a structured tool, execute_python exposes the full remote bpy API. This covers arbitrary geometry, nodes, animation, rigging, simulations, editor overrides and supported add-ons. It does not make a missing add-on available automatically. Dynamic enum choices are resolved from registered callbacks when possible; unresolved or truncated choices are marked with items_complete:false. Dynamic defaults can be unavailable in raw RNA, so choose a listed enum identifier instead of blindly copying an empty default.

Use inspect_object and inspect_nodes to verify changes, then inspect a viewport image or camera render. inspect_dependencies reports its coverage limit and is not a complete dependency closure. get_logs reads native Blender output while the session runs; ended sessions return persisted worker diagnostics, including startup error details. Successful inspection does not prove that every add-on or simulation engine has been tested.

Requests use stdin rather than command-line arguments. Remote execution-control requests have a 35-second deadline; if a response is lost, the operation's outcome may be unknown. Inspect session/job state before retrying a mutation. Structured job results are limited to 1 MB; write larger data to workspace files. File listings are paginated, and internal state and symbolic links are excluded.

Additional billable failure-path checks:

uv run python scripts/validate_lifecycle.py
uv run python scripts/validate_recovery.py

See debug audit and coverage for the verified tool coverage and regression results. Existing sandbox runtimes are immutable; stop them and start fresh sessions after a server update. Restart Codex to reload expanded tool schemas.

Multiple independent renders

Codex owns splitting the request, spawning subagents, scheduling, retries and aggregation. Project guidance is in AGENTS.md. The MCP does not interpret the user request or provide an agent scheduler, task broker, worker-assignment service or batch ledger.

The resource primitive is:

create_session(project="my-project", new_workspace=true)

Each call creates a fresh Blender process, Sandbox, persistent Volume, scene, queue and checkpoint namespace. Two callers may use the same project label and the same remote filenames without sharing state. Provisioning locks are scoped to the workspace, so one workspace does not serialize another's startup. Resource identifiers include a UUID namespace distinct from ordinary project names.

The response includes session_id, workspace_id, sandbox_id and volume. A worker uses only its own session ID. Codex assigns a unique local output directory to each item, downloads and checks its files before stopping compute, and combines the reported results. The existing download tool refuses to overwrite a local file; output layout remains Codex's choice.

Reopen an independent workspace after termination with:

create_session(project="my-project", workspace_id="<returned workspace UUID>")

Add restore_revision to select one of that workspace's checkpoints. Do not combine new_workspace=true with an existing workspace_id or recovery revision. Omitting both isolation options preserves the existing default-workspace behavior.

This is resource separation for a trusted harness, not access control between hostile tenants. Agent count and resource budgets remain the harness's responsibility. Each active sandbox incurs its own Modal charges and retains its saved Volume after compute stops.

Available Tools

26 tools
cancel_jobC

Request cancellation. Running jobs restart Blender from its last checkpoint.

Inputs: job_id (required), session_id (required).

control_viewportA

Control the live Blender GUI: select/frame objects, orbit, pan, zoom and shade.

Requires a GUI session. Rotation is XYZ Euler angles in degrees; target pans
the view center. Changes persist in the live viewport. Capture with viewport_screenshot
after this job succeeds. Software graphics rendering happens remotely.

Inputs: session_id (required), view, frame, select, +6 more.

create_sessionA

Start or reconnect to a project. GPU resources incur charges until stopped.

First creation builds a Blender image and can take several minutes. Existing
projects restore their last checkpoint. Set restore_revision to recover an older
checkpoint at startup if the latest one is unusable; stop any active session first.
new_workspace=true creates a new independent Blender/Sandbox/Volume, even for the
same project label. Returned workspace_id can reopen that exact workspace later.
Without either option, the default project workspace is reused. Agent spawning,
scheduling and aggregation are entirely the caller's responsibility.

Inputs: project (required), gpu, mode, idle_seconds, +4 more.

describe_apiB

Discover installed operators or inspect real RNA property schemas, enums and defaults.

Omit name and use query to search operators, e.g. export or mesh. Give an exact
operator (mesh.primitive_cube_add) or RNA type (Object) for its schema. No eval.

Inputs: session_id (required), name, limit, query, +2 more.

download_fileC

Download a workspace file to a new local filename. Maximum size 5 GB.

Inputs: local_path (required), session_id (required), remote_path (required).

execute_pythonB

Queue arbitrary Python in persistent Blender. Full bpy and remote OS access.

Assign a JSON-serializable value to result. Variables are per call; bpy scene state persists. Successful calls save a checkpoint by default. A timeout or running-job cancellation restarts Blender and loses unsaved changes.

Inputs: code (required), session_id (required), checkpoint, timeout_seconds.

get_environmentB

Inspect actual Blender/Python versions, enabled add-ons, devices and GUI capabilities.

Inputs: session_id (required).

get_logsA

Read the tail of Blender's native log for errors not captured in Python stdout.

Inputs: session_id (required), max_bytes.

inspect_dependenciesC

Report packed/missing assets and resolved paths. Reports coverage limits explicitly.

Inputs: session_id (required), limit, offset.

inspect_nodesC

Inspect shader, geometry or compositor nodes, sockets and links with pagination.

Inputs: name (required), session_id (required), limit, offset, +1 more.

inspect_objectC

Inspect mesh counts, transforms, materials, modifiers, constraints, rig and animation action.

Inputs: name (required), session_id (required).

inspect_sceneC

Inspect Blender version, frame and object transforms with pagination.

Inputs: session_id (required), limit, offset.

job_statusB

Read a job, including results, stdout and tracebacks. Optionally wait up to 30s.

Inputs: job_id (required), session_id (required), wait_seconds.

list_checkpointsB

List saved revisions that can be restored, newest first.

Inputs: session_id (required). Returns: result

list_filesC

List up to 1000 workspace files, excluding internal state.

Inputs: session_id (required), path, limit, offset. Returns: result

list_sessionsA

List locally recorded sessions. Records can include ended sandboxes.

Inputs: no named parameters. Returns: result

open_projectA

Replace the live scene with an uploaded .blend; disables embedded script auto-run.

Save current edits first. Successful open creates a new checkpoint.

Inputs: path (required), session_id (required).

renderA

Queue a Cycles camera render. Requires a camera; GPU requires a GPU session.

Returns a job ID. On success view_image retrieves the PNG. The live session
serializes renders with edits. Render settings are restored after the job.

Inputs: session_id (required), frame, width, device, +3 more.

restore_checkpointB

Replace the live scene with a saved revision. Save current edits first.

Inputs: revision (required), session_id (required).

run_operatorA

Run an installed Blender operator with structured arguments and optional GUI context.

Use describe_api first. Supports modeling, modes, import/export, baking and more,
as available in this build. EXEC_DEFAULT must report FINISHED. Mutations save by
default. Prefer execute_python for custom logic, data APIs or modal UI interactions.

Inputs: name (required), session_id (required), context, checkpoint, +2 more.

save_projectC

Queue a durable checkpoint. Optional new workspace path exports a .blend for download.

Inputs: session_id (required), path.

session_statusC

Inspect remote worker, checkpoint and recent jobs; refresh user activity.

Inputs: session_id (required).

stop_sessionA

Save a checkpoint and terminate compute. Project volume and revisions persist.

Drains accepted jobs before saving; rejects new jobs while draining. A pending
save returns stopped=false and its job ID. Retry after it finishes. Setting
discard_unsaved=true terminates immediately and loses unsaved edits.

Inputs: session_id (required), discard_unsaved.

upload_fileC

Upload a local file to a new relative workspace path. Never overwrites.

Inputs: local_path (required), session_id (required), remote_path (required).

view_imageA

Return a workspace PNG as inline MCP image content (maximum 10 MB).

Inputs: path (required), session_id (required).

viewport_screenshotA

Capture the actual Blender GUI window and return an inline image plus its artifact path.

Requires a GUI session. This includes viewport overlays, selection and editor UI.
It is separate from a Cycles camera render. If the job is still queued, poll its ID
and retrieve the resulting artifact with view_image.

Inputs: session_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 26 tools

    Disambiguation4/5

    The tools mostly target distinct resources and actions, and the descriptions clarify overlaps. The main gray areas are the cluster of inspect_* tools (scene/object/nodes/dependencies), which are separable by description but could be mistaken for one another, and the render vs viewport_screenshot vs view_image trio, which requires reading the descriptions to keep straight.

    Naming Consistency4/5

    Nearly all tools follow a snake_case verb_noun pattern (list_sessions, inspect_object, run_operator, save_project, upload_file). A few deviations exist: noun-first names like session_status and job_status, the noun_noun viewport_screenshot, and the bare verb render. Still largely readable and consistent.

    Tool Count3/5

    26 tools is at or above the heavy threshold, but the scope is genuinely broad—sessions, jobs, multiple inspection types, execution, rendering, checkpoints, and file IO. Each tool maps to a distinct operation, yet the surface is on the large side and some inspection tools could potentially be consolidated.

    Completeness4/5

    Coverage is strong across the full lifecycle: session management, job control, scene/object/node inspection, arbitrary execution, rendering, checkpoints, and file transfer. Minor gaps exist—e.g., no file delete/move and no explicit checkpoint deletion—but core workflows are fully covered.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables remote control of Blender via the Model Context Protocol, allowing users to execute Python scripts, query scene data, and generate 3D models from images. It provides a bridge for AI clients to interact directly with Blender's internal environment and automate 3D content creation.
      3
      6
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables remote control of Blender through MCP, allowing code execution, scene manipulation, rendering, and file transfer in a containerized environment.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI clients to control a running Blender instance through the Model Context Protocol, allowing scene inspection, object creation and editing, rendering, and execution of Blender Python. It works locally via a WebSocket bridge between the MCP server and a Blender add-on.
      15
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable AI clients to control a local Blender workstation through a secure HTTP gateway for 3D scene inspection, modeling, rigging, animation, materials, rendering, import/export, and controlled Python automation. Supports permission profiles and authentication modes to keep Blender execution local while allowing AI-assisted production workflows.
      1
      MIT