Remote Blender MCP
Controls Blender scenes remotely with full access to bpy: execute Python and operators for modeling, rigging, animation, geometry nodes, materials and import/export; inspect scene objects, nodes and RNA API schemas; control and screenshot a live GUI viewport; render with Cycles (CUDA/OptiX); and save, restore and download .blend projects and checkpoints.
Provisions and manages the remote compute and storage backing each Blender session: creates persistent sandbox workers on Modal (CPU or GPU), mounts a per-project Modal Volume as a workspace, tracks session/job status, and tears down compute while preserving saved project data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Remote Blender MCP Create a headless session, add a blue sphere, and render it."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 setupInstall the Codex configuration for this checkout:
uv run python scripts/setup_codex.pyThis 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
Call
create_sessionwith a project name such asdemo. Usemode="gui"for viewport control ormode="headless"for batch work. The default uses CPU and headless mode. Leavegpuunset 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.Call
inspect_scenewith the returnedsession_id.Call
execute_python, thenjob_statusuntil the job succeeds or fails. Assign a JSON-serializable value toresultto return data.Call
render, then inspect its job. Callview_imagewith the resulting relative PNG path for inline visual feedback.Call
save_projectwith a new path such asexports/scene.blend, wait for success, and usedownload_fileto retrieve it.Call
stop_sessionto 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 |
| Manage remote compute and reconnect using the local registry. |
| Full Python access or structured operator execution, including modeling, import/export and baking. |
| Scene transforms, mesh counts, modifiers, materials, constraints, rig and animation action. |
| Shader, Geometry Nodes, world and compositor graphs, sockets and links. |
| Search installed operators and inspect actual RNA schemas, enums and defaults. |
| Discover runtime capabilities, diagnose errors and check asset references. |
| Control and inspect the actual remote GUI viewport. Requires GUI mode. |
| Create camera renders and return inline PNG images. |
| Retrieve results, tracebacks and logs; stop queued or running work. |
| Save checkpoints, export a |
| List and restore saved scene revisions. |
| 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.pyIt 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.pySee 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 toolscancel_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
Scored across 26 tools
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.
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.
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.
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
Cloud Blender for AI agents: build, inspect, render and animate 3D scenes over remote MCP. Keep editable .blend projects and export GLB or STL. Make your first 3D asset free—30 compute minutes per UTC month, no credit card. First 100 eligible Free account owners to use all 30 minutes in one UTC month by December 31, 2026 UTC receive one calendar month of beta free: 4 compute hours per UTC month, 2 concurrent workers per deployment, 2 deployments, 2048×2048 renders at up to 256 samples, and 10 GiB storage. Existing usage counts toward the 4-hour allowance. Limited to 100 rewards; expires January 1, 2027 00:00 UTC. Free resumes afterward without an automatic charge. Examples, eligibility and terms: https://sceneplane.online/launch?utm_source=glama&utm_medium=directory&utm_campaign=first100
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.36MIT
- FlicenseNot gradedqualityCmaintenanceEnables remote control of Blender through MCP, allowing code execution, scene manipulation, rendering, and file transfer in a containerized environment.1-
- AlicenseAqualityCmaintenanceEnables 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.15MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT