Blender Bridge

Accept an invitation after the user agrees to its shown your_role. For receive, pass your own listed device_id to receive commands in that Blender. For control, no local computer is needed and the shared computer is selected automatically.

Cancel a Blender Bridge operation by request id. Background renders stop their owned Blender process immediately. Queued work is skipped; other already-running Blender Python uses cooperative cancellation.

Test whether the receiving Desktop Bridge and Blender add-on are reachable, authenticated and compatible for work. Returns readiness, component/contract details and a concrete blocker when the local runtime is unavailable. Does not execute a scene command or launch Blender. Use after a connection failure; get_connection instead lists account computers and session access, while get_setup_status provides the broader setup diagnosis.

Save one PNG with the active camera reference photo on the left and the latest PNG/JPEG render on the right, preserving aspect ratios. Render an image first. Does not match perspective or alter the scene/source images. Existing outputs are refused.

Refuse a pending collaboration invitation addressed to this account after the user requests it. id comes from incoming invitations in get_connection. Marks the invitation declined and returns refreshed connection state; does not accept or start shared-computer access. Use accept_collaboration if the user agrees to join, or end_collaboration to end an already pending/active session in which this account participates. view_decline_invitation is the app-panel adapter.

End a pending or active session you participate in, regardless of who initiated it. Friendship remains separate.

Install or repair the bundled Blender Bridge extension for the receiving Desktop's selected Blender installation. Can overwrite the bundled add-on and reload it; Desktop may be started to perform the action. Returns installation/control status. Use when setup identifies a missing or incompatible extension or the user requests repair, rather than as an unconditional step before modeling. get_setup_status checks readiness; restart_blender_with_extension explicitly relaunches Blender when needed.

Execute Blender Python code through Blender Bridge. operation_name is required and must be a short, concrete, user-facing history title in the user's language, never a generic Run/Execute label. Persistent save/render/export work must include the structured project and outputs fields; use prepared paths through bb_output_path(kind_or_id). If Bridge returns ProjectRequired, supply the requested destination or use its suggested workspace path when file organization was delegated; ask only for a missing user choice. get_llm_instruction / blender://instructions/llm provides protocol and helper details when needed. Connection failures return their resolution. Default response_mode 'compact' returns only logs, delta, scene_digest and a slim scene snapshot (when changed). Use 'full' only for deliberate protocol diagnostics, not ordinary save/render verification. Long operations automatically return a running request_id before common MCP-host call limits; poll get_blender_operation_status instead of repeating the command. Set include_screenshot=true when the command result and the current viewport screenshot must be delivered by the same request.

Export existing mesh content as a GLB result for a web or compatible 3D viewer, converting scene units to meters. The project/filename options choose a new output and operation_name is its history title. Existing output destinations are refused rather than overwritten. Returns export/output status; poll a returned running request_id instead of starting the export again. Use export_model for target-specific FBX, USDZ or STL workflows, save_blend_file for a complete editable Blender scene, or get_project_file to retrieve a result already created.

Export mesh models for web/Godot (GLB), Unity/Unreal (FBX), USD (USDZ), or 3D printing (STL in millimeters). Reports axes, units, file size and material warnings. GLB/FBX/STL respect scene unit scale; USD currently requires unit scale 1 and refuses other scales. Scene transforms stay unchanged; verify the file in the destination editor. Existing destinations are refused.

Ask the running receiving Desktop to discover installed Blender executables and versions. Returns installation choices without selecting or launching one and does not auto-start Desktop. Use when choosing an installation at the user's request. select_blender saves the chosen executable; get_app_state reports the current selection and Desktop status.

Search free CC0 HDRIs, textures and models from Poly Haven and ambientCG without touching the scene, so the search adds no undo step. These are optional resources: searching does not request download or application. A chosen asset can be used in execute_blender_code with bb_get_asset and bb_use_hdri, bb_make_pbr_material or bb_import_model. Search words work best in English. Quote the asset's credit to the user: Poly Haven's terms require naming the source.

Read the receiving Blender Bridge Desktop application's configuration and status: version, account access, Bridge, selected Blender, workspace, extension, connected chats, language and updates. Does not auto-start Desktop or execute a Blender command. Use for Desktop settings and process diagnostics. get_connection instead describes this chat's account computers and collaboration, get_setup_status diagnoses the complete connection, and get_scene_state inspects scene content.

Read version and protocol diagnostics from a ready Blender runtime, together with a compact scene summary. Returns server_info, Bridge/add-on contracts and scene_summary; requires a production-ready receiving Bridge and Blender. Use to diagnose runtime or version compatibility. Use get_scene_state for detailed scene inspection, check_connection for readiness only, or take_screenshot for visual appearance. Does not modify the scene.

Poll a long Blender command, background render or screenshot by request_id. Returns running, completed, cancelled, or failed without re-executing it.

Optional task workflows for product shots, interiors, characters, ad clips and photo reconstruction or compositing, with bb_ helper examples and result checks. Available: ad-clip, interior-scene, match-photo, product-shot, stylized-character. Read a relevant recipe when it helps the task; call without a name to list them with descriptions. Adapt examples to the user's reference, proportions, requested style and measured CPU/GPU render budget. Numbers are starting points, not quality guarantees. Reading a recipe does not touch the scene.

In MCP Apps chats, call open_blender_view at the start of scene work if no workspace is open. The panel is for the user and updates itself. Do not reopen it after each command; inspect results with scene/screenshot tools. Inspect this chat's account access, selected computer, own/shared computers, incoming invitations and friends without opening a visual panel. An already accepted shared session can become selected. Returns connection/session state; does not create an invitation or grant new access. Use check_connection for receiving Bridge/Blender health, get_setup_status for setup blockers, get_app_state for Desktop configuration, or open_blender_view for the interactive panel.

Read connection instructions for the installed Desktop plugin, direct local MCP, Internet chat connectors and the browser extension fallback. Use the method supported by the chosen host; a Desktop plugin can offer Local and Remote modes.

Read the relevant Blender Bridge reference without loading unrelated chapters. Default core covers task scope and command completion. Use scene for creation/editing (core, visual craft and version-specific API); files for save/render/export/delivery; connection, api, assets, helpers or film for those topics. all returns the complete original reference. No creative sequence or file delivery is required by loading a reference.

Get a requested result by workspace-relative path, latest scene/render/video/model, or output_id returned by an explicit external-path file tool. Local: disk path. Remote: a temporary download link. External output permissions last 24 hours in the current Desktop/MCP processes and cannot read other external files.

Inspect the current scene in the receiving Blender and return structured scene_state with runtime metadata and a text summary. full defaults to true; false requests the compact scene-state form. Uses a pass-only Bridge probe and does not change scene objects or create a screenshot. Requires account access and a working receiving Bridge/Blender. Use before deciding how to edit a scene; get_blender_info is for version/protocol diagnostics and take_screenshot is for visible appearance.

Diagnose readiness to work in the receiving Blender: account access, Desktop Bridge, Blender add-on and their compatibility. Returns structured setup/component state and the next action for a blocker; does not execute a scene command. Use when setup or access is uncertain. get_connection instead lists account computers and collaboration for this chat, get_app_state reads Desktop configuration, and check_connection is the focused Bridge/Blender connectivity check.

Start a bounded session by email or confirmed friend. role=control (default) requests using the recipient's Blender and requires no computer on the sender. role=receive offers your own listed device_id. The recipient sees the opposite role and accepts once. Roles apply only to this session; friendship never grants access.

List computers of this account, their Blender and online state, and the computer selected for this chat.

Read confirmed friends and pending friend invitations. Synchronizes your verified email/name in existing contact records when changed. Friendship alone grants no Blender access.

Discover existing output files in the receiving Desktop application's configured project workspace. Optionally filter kind to scene, render, video or model and cap the number of results with limit. Returns file metadata and workspace-relative paths; remote responses omit absolute disk paths. Requires the receiving Desktop to be running and accessible. Does not create, render or upload a result and does not auto-start Desktop. Use get_project_file with a returned relative path to retrieve a file; view_files is the app-panel adapter.

Look up the real Blender Python API without touching the scene: types with their properties, enum values and functions, operator parameters, node input and output socket names, and which Blender versions have a name. Use it before code that relies on names you are not sure of, and after AttributeError, KeyError or TypeError. query: an exact name (ShaderNodeBsdfPrincipled, Material.use_nodes, bpy.ops.wm.obj_import, ShaderNodeBsdfPrincipled.Emission Color) or keywords (glare bloom). blender_version: the user's Blender version if known; otherwise the version from the latest scene state is used.

Change a contact relationship after the user chooses the action. request sends a friend request to email; accept, decline and remove act on an existing invitation/contact id from list_friends. Returns refreshed contact state. Friendship alone grants no Blender execution or computer access: use invite_collaborator for an explicitly approved session. Use list_friends to inspect contacts without requesting a relationship change; view_manage_friend is the app-panel adapter.

Launch the Blender installation selected in the receiving Desktop application when the user wants to work in Blender. Requires that computer and Desktop to be available with active account access. Desktop can install or update its bundled Blender extension before launching; repeating the call can open another window. Returns launch status, not a screenshot or a completed scene. Use get_setup_status to check readiness and open_blender_view to open only the chat panel.

In MCP Apps chats, call open_blender_view at the start of scene work if no workspace is open. The panel is for the user and updates itself. Do not reopen it after each command; inspect results with scene/screenshot tools. Open the interactive Blender Bridge workspace in a chat host that supports MCP Apps: connection and computer selection, scene previews, checkpoint history, project files and operation progress. Does not launch Blender or execute scene code. A connection scope or an already accepted shared route may be selected. Use get_connection for text-only connection state, open_blender to launch Blender, or take_screenshot for a fresh image.

Check an existing account sign-in flow started by start_auth and report its current state. When the browser confirmation is complete, polling can exchange the flow and save the resulting account credentials; it is not merely a read-only status lookup. Does not start another browser sign-in. Desktop-managed connections instead report the current receiving Desktop account's readiness and do not exchange a separate MCP flow. Use for pending sign-in completion, get_connection for account/computer state, or get_setup_status for runtime readiness.

Prepare and attach a high-quality branded PNG of the current Blender 3D viewport for an explicitly requested share or export workflow. This tool only prepares the image; it never publishes, opens a social network, or authenticates to one.

Render the receiving Blender scene to a PNG result at the requested project destination. Optional frame, width, height and samples control the render; operation_name is the user-facing history title. The call writes an output and explicit overwrite authorization is required to replace an existing destination. Long renders return a running request_id: poll get_blender_operation_status instead of repeating the render. Use take_screenshot for a quick viewport inspection without a final render, or get_project_file to retrieve an existing rendered result.

Close and relaunch the selected receiving Blender with its Blender Bridge extension after the user requests or agrees to a restart. Can interrupt current work; unsaved changes may require confirmation inside Blender. Desktop may start if its control service is unavailable. Returns restart/control status, not a completed scene. Use get_setup_status for passive diagnosis or ensure_blender_extension for installation/repair without requesting a full restart.

Load a packaged Blender Bridge demonstration scene in the receiving Blender after the user requests a test. scene_id selects logo (default) or cube. This changes the current scene and can replace existing contents; preserve user work before using it. Requires account access and a working paired Bridge/Blender. Returns the scene-operation result and request metadata. Use get_scene_state or check_connection for inspection without loading a demonstration; this tool is not needed before ordinary modeling.

Save a .blend copy of the current complete scene to the requested project destination while preserving the open project and its unsaved state. The destination options choose the project folder and filename; operation_name supplies the user-facing history title. Replacing an existing output requires explicit overwrite authorization. Returns copy/output status, possibly a running request_id for work still in progress. Use get_project_file to retrieve an existing result or export_model for an interchange format instead of a Blender scene file.

Scene history, newest first. For returning to a named step, action list supplies its explicit after_state_checkpoint_id and after_state_restorable: restore that checkpoint_id for the state AFTER that command. Never substitute the next command's before checkpoint. before_request_id intentionally means BEFORE a command, as does undo_last_action. Returns add a current history entry and a backup; Undo return requires expected_current_checkpoint_id and is invalidated by new work. action save creates a named point now.

Search the official Blender manual (offline copy of the current release, CC-BY-SA 4.0) without touching the scene: how a feature, modifier, node or render setting works, what an option does, where it is in the interface, and recommended workflows. Use lookup_blender_api for exact Python names instead. query: a few English words (bevel modifier segments, depth of field focus, light linking). Returns the best sections with excerpts and page links; link the page when you quote it to the user.

Save the Blender executable that the receiving Desktop should use for subsequent actions. path identifies an existing compatible Blender 4.2+ executable on that computer. Changes a persistent selection and can start Desktop if its control service is unavailable. Returns selection/control status. Discover choices with find_blender_installations; open_blender is the separate launch action. Use only when the user wants to change the selected installation.

Choose a listed own or shared computer for this chat, including an offline computer. Commands to an offline selection fail without using another computer.

Change the saved interface language of Blender Bridge Desktop on the receiving computer. language is one of the supported language codes. Use only when the user asks to change that interface; this is not a translation tool for scene content, project files or chat replies. Returns the Desktop control result. Use get_app_state to inspect the current language before changing it.

Choose local for Blender on this computer, or remote with a listed device_id for another computer or a shared session. Read get_connection first; review the returned scope before another change.

Change the receiving Desktop application's configured project folder. path is a folder on that computer, not on the chat device. Subsequent project-file operations use this workspace. This changes a persistent setting; use only when the user requests a different project location. Use list_project_files to inspect existing results or get_project_file to retrieve one.

Put a reference PNG/JPEG behind the scene camera. Pass a project image path, a public HTTPS URL, or the file object from the chat. Downloaded files go to workspace inputs/. Returns image dimensions and path.

Request sign-in state for the receiving MCP connection. Standalone MCP can create a browser account flow; open_browser defaults to true. The user enters credentials only on the account website. A new standalone flow can replace a pending one; use poll_auth_status to check an existing flow. Desktop-managed receiving connections use the current Desktop account and return its readiness or a request to resolve access there, without a separate MCP sign-in.

Start the authenticated Desktop-to-Blender Bridge service on the receiving computer. Requires existing account access and may start Desktop first. Reuses a healthy Bridge; recovery can stop and replace an unhealthy owned Bridge process, interrupting its connections. Returns the control action's status. Use when the user needs the Bridge running; get_app_state or check_connection inspects status without starting it, stop_bridge stops it, and open_blender separately launches Blender.

Stop the receiving Desktop's Bridge service when the user wants to end that connection or agrees to recovery. This interrupts Bridge-based tool connections and can interrupt in-flight requests; it does not delete scene/project files or request a Blender restart. Returns stopped/control status. Use start_bridge to bring the service back. Prefer get_app_state or check_connection for passive inspection: this control action can start Desktop first if its control service is unavailable.

Capture a screenshot through the local bridge and return it as tool output. Defaults to the current 3D viewport; pass source="camera" only when the user explicitly wants the active camera view.

Capture a screenshot artifact through the local bridge and return only URL/metadata, without inline base64 or image attachment. Use this for batch/reference screenshots when the model does not need the image embedded in the tool result.

Undo the latest AI change that really changed the scene by returning the whole scene to the checkpoint saved before it. Later AI steps and manual edits since then are reverted too; the state before the undo is saved, so the undo itself can be reverted. With request_id, return to the state before that request. Tell the user what was reverted.

App-only adapter for the connection panel's Accept invitation button, after the user agrees to the displayed session role. id identifies an incoming invitation addressed to this verified account. For your_role=receive, supply an own listed device_id: this permits the other participant to control that computer. For your_role=control, no receiving computer is required from this account. Accepting changes session access and selection; returns updated connection state. Models should use accept_collaboration; use view_decline_invitation to refuse instead.

For the Blender panel: read long-operation state without executing or waiting for Blender.

App-only adapter for the Blender Bridge panel's capture and viewpoint controls. Starts a fresh screenshot operation in the receiving Blender and stores its preview; this can return operation progress before completion. view selects the current viewport, camera or a requested viewpoint and defaults to viewport. auto marks a panel-triggered automatic capture rather than a user click. Requires account access and a working Blender. Use view_latest to read an existing preview without capture; models should use take_screenshot for a fresh image.

App-only adapter that refreshes account access, selected computer and available computer/session state in the connection panel. Returns a panel connection payload rather than opening another workspace. An already accepted shared session may become the selected route. Does not launch Blender or create a new access grant. Models should use get_connection for the same connection information without a visual panel, or get_setup_status to diagnose runtime readiness.

App-only adapter for the connection panel's Decline invitation button. id identifies a pending incoming invitation addressed to this verified account. Marks that invitation declined and returns refreshed connection state; does not accept access or start a shared session. device_id is not used for declining. Models should use decline_collaboration; end_collaboration is the separate action for ending an existing session.

App-only adapter for the file panel's Download and Reveal controls. path is a workspace-relative result selected in that panel. action defaults to download: remote delivery uploads the requested existing file and returns a temporary download link in view.download; treat that link as bearer access to the result. reveal shows a validated local file in its containing folder when supported and returns view.reveal. Does not render or save a new scene. Models should use get_project_file for delivery, or list_project_files to discover existing outputs.

App-only adapter for the panel's End session button. id identifies a pending or active collaboration involving this account. Revokes that session's access and returns refreshed state; it does not remove a friendship or sign out Desktop. Models should use end_collaboration; decline_collaboration is for refusing an incoming invitation.

App-only adapter for the project-file list and image-preview area in the Blender Bridge panel. action=list returns existing workspace file metadata in view.files; it needs no path. action=preview requires a workspace-relative file path from that list and returns a bounded preview in view.preview. Absolute disk paths are omitted from the list payload. Does not save, render or prepare a download link. Missing paths or failed file reads return project_file_action_failed. Models should use list_project_files to discover results and get_project_file to retrieve a requested file.

App-only adapter that refreshes the Blender Bridge panel's friend list and pending friend invitations. Returns contact state; verified account identity can be synchronized in existing contact records. Friendship itself grants no Blender access. Models should use list_friends rather than this panel adapter.

App-only adapter for the history list in the Blender Bridge panel. Reads up to 100 scene-checkpoint records and returns them in the panel view.history payload. action, when supplied, must be list. Requires account access; does not restore a checkpoint or modify the scene. Models should use scene_checkpoints for history operations; the panel uses view_restore when the user selects a checkpoint to restore.

App-only adapter for the panel's Invite participant control. Creates a session invitation to email or friend_id. role=control requests the recipient's Blender; role=receive offers this account's listed device_id. The recipient must approve before shared access is active. Returns invitation/session state. Models should use invite_collaborator rather than this panel adapter.

App-only adapter that reads the panel's latest existing preview and view-state counters. since is the last preview sequence already displayed; scene_version and instance_id identify the panel's last known scene and runtime. Optional wait_ms waits up to 25 seconds for a change. Does not start a new capture or render. Requires account access. The panel uses view_capture to request a new image; models should use take_screenshot when they need to inspect current appearance.

App-only adapter for the panel's friend-request and contact-management buttons. action=request uses email; accept, decline and remove use the relevant contact/invitation id. Can send a request or change a contact relationship after the user chooses the action. Returns updated contact state; grants no Blender-session access. Models should use manage_friend, and invite_collaborator for an actual shared Blender session.

App-only adapter for joining a shared-computer invitation from its Blender Bridge invite_url. Records a request for this verified account; the receiving computer owner must review and approve it before access is active. The invitation URL is validated as a first-party session invitation, not fetched as an arbitrary web page. Returns refreshed connection/session state in an Internet workspace. Use invite_collaborator instead to create a new invitation by email or friend.

App-only adapter for the panel's Restore and Undo restore buttons, used after the user chooses a history entry. Replaces the current scene with a checkpoint and can discard subsequent manual or AI edits. Supply checkpoint_id or before_request_id from the history records. undo_restore also requires expected_current_checkpoint_id to reject a changed current scene. Returns updated history and the restore result; cross-file restoration is refused. Use view_history to read the panel history, or scene_checkpoints for model-driven history actions.

App-only adapter for the connection panel's computer selector. device_id identifies an own or approved shared computer listed for this account. Changes the target for this conversation, not its transport or access permissions, and returns refreshed connection state. A selected offline computer is not silently replaced with another target. Does not launch Blender. Models should use select_computer on the hosted connector or set_connection in a native Desktop plugin.

App-only adapter that refreshes the workspace's shared-session status and incoming invitations for the collaboration panel. Returns connection/session metadata in an Internet workspace and does not create an invitation or accept access. An already accepted shared route may become selected. Use get_connection for model-driven account/session inspection; view_request_session is the separate action for requesting access through an invitation URL.

App-only adapter for a native Desktop plugin workspace's Local/Remote selector. Changes only that workspace's route and epoch; a foreground write blocks switching. mode selects the transport and device_id identifies a listed Remote computer. Review the returned scope before the next write. A fixed hosted connection does not support native transport switching. Models should use set_connection; the panel uses view_select_computer to change a computer without changing transport.

App-only adapter for the connection panel's Sign in button, used after an explicit user click. A local/native connection creates a browser sign-in flow and returns its connection URL; the hosted connector returns an authentication challenge for the chat host. Credentials are entered only on the Blender Bridge account website, never as tool arguments. Starting another local flow can replace the pending flow. Models should use get_connection to inspect access; start_auth is the separate receiving/standalone MCP sign-in action.

For the account panel: sign out this connection after the user presses Sign out. Does not sign out the receiving Desktop.