GameCult/Brokkr
Watch
9
0
Fork
You've already forked Brokkr
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Research: Blender MCP servers as the capability bar for Brokkr

Browse source 
Eyes pass 2026-10-10: tools, limits and security posture of the official
Blender Lab MCP, the community BlenderMCP and Blender Agent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-10 03:00:16 +02:00
commit f97d4dcbb7
1 changed files with 43 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

43
docs/research/blender-mcp-capability-bar.md Normal file
View file

@ -0,0 +1,43 @@
# Blender MCP servers: the capability bar for Brokkr
Eyes pass, 2026-10-10. Operator: "I want brokkr to be superior to blender mcp". What the official Blender Lab MCP, the community BlenderMCP and the Blender Agent fork expose, for a collaborative modelling loop needing (a) viewport sight, (b) selection reading incl. Edit Mode vertices/faces, (c) code execution, (d) API docs. Facts only; tags mark FETCHED, SEARCH and KNOWLEDGE (unverified).
# Blender MCP facts (Eyes, 2026-10-10). Tags: FETCHED=read from source/API this session; SEARCH=web summary; KNOWLEDGE=memory.
Raw copies of the sources read sit beside this file in lab/ and ahuja/.
## A. Official Blender Lab MCP (projects.blender.org/lab/blender_mcp)
- Version: release v1.0.3 "Screenshot Fix" 2026-09-11 (blender-1.0.3.mcpb + mcp-1.0.3.zip); v1.0.2 "MCP SDK Fix" 2026-09-08; 6 releases. FETCHED (API /releases). Inside files: mcp/pyproject.toml 1.0.2, mcp/manifest.json 1.0.2, add-on blender_manifest.toml 1.0.0. FETCHED
- Blender >= 5.1.0 (blender_manifest.toml blender_version_min). FETCHED. Server Python >= 3.10, mcp[cli]>=1.2,<2. FETCHED
- Licence: GPL-3.0-or-later (add-on manifest, manifest.json, LICENSE 35 KB). FETCHED
- Architecture: Blender add-on runs a TCP socket server inside Blender; a separate stdio MCP process (`blender-mcp`) relays code to it. "All tools send code to the add-on to run." FETCHED (readme.md, blmcp/__init__.py)
- Security: blender.org page warns it runs LLM code "without any guards"; use a VM. SEARCH (WebFetch of blender.org/lab/mcp-server). Add-on has a "weak sandbox" (blocks sys.exit, wm.quit_blender, wm.read_factory_settings etc.); its own docstring: "isn't really a sandbox". FETCHED (weak_sandbox.py)
- Socket: add-on DEFAULT_HOST "localhost", DEFAULT_PORT 9876; host/port in add-on prefs, optional auto-start; client env BLENDER_MCP_HOST / BLENDER_MCP_PORT. No auth token: grep for token/auth in mcp_to_blender_server.py and connection.py found none. Manifest permission text: "Runs a local TCP socket server". FETCHED
- Add-on _CLIENT_TIMEOUT = 10.0 s (stalled connections evicted); deferred responses (check_is_finished) exist for long jobs. FETCHED
- Optional HTTP transport (--transport http, default 127.0.0.1:8000): CORS allow_origins "*", DNS-rebinding protection disabled. stdio is default. FETCHED (blmcp/__init__.py)
- Tools (readme_tools.rst, 28 names): execute_blender_code, execute_blender_code_for_cli, get_blendfile_summary_{datablocks,missing_files,of_linked_libraries,path_info,usage_guess} (+ _for_cli variants), get_object_detail_summary, get_objects_summary, get_python_api_docs, get_screenshot_of_area_as_image, get_screenshot_of_window_as_image, get_screenshot_of_window_as_json, jump_to_tab_by_name, jump_to_tab_by_space_type, jump_to_view3d_object_by_name, jump_to_view3d_object_data_by_name, render_thumbnail_to_path, render_viewport_to_path, search_api_docs, search_manual_docs. FETCHED
- (a) viewport: get_screenshot_of_area_as_image(area_ui_type: Literal VIEW_3D|IMAGE_EDITOR|UV|ShaderNodeTree|GeometryNodeTree|OUTLINER|PROPERTIES|SPREADSHEET|..., size_limit_in_bytes:int=0) -> PNG Image. Uses bpy.ops.screen.screenshot_area; default cap (1_048_576-2048)*3//4 bytes (~785 KB, so base64 fits a 1 MiB MCP message); errors in background mode. get_screenshot_of_window_as_image captures the whole window. v1.0.3 note: "Fix the long standing screenshot capture tool". render_viewport_to_path(output_path) renders with current render settings to a file path (no image returned). FETCHED. Downscale helper body is injected from _template_image_downscale_to_size_limit.py; not read.
- (b) selection: get_screenshot_of_window_as_json() returns window layout, active object, context.mode, selected_objects as [{name,type}] only. get_objects_summary() returns collection tree, per object name/type/parent/data name/selected/visibility, plus object_mode. get_object_detail_summary(name) returns type, transforms, parent, children, modifiers, constraints, materials, visibility, data name, collections. NO tool returns selected vertices/faces or coordinates; that needs execute_blender_code with bmesh. FETCHED (toolcode files). prompts.yml tells the LLM "In edit mode, access mesh geometry through the bmesh API" and to set mode/selection explicitly. FETCHED
- Edit Mode data readable without leaving Edit Mode: code runs in the live session, so bmesh.from_edit_mesh works there; no tool forces a mode switch. KNOWLEDGE (bpy behaviour), not tested.
- (c) code: execute_blender_code(code:str) -> dict; full bpy; return data by assigning a dict to `result`; non-JSON values repr'd; destructiveHint=True. execute_blender_code_for_cli(blend_file, code) runs in `blender --background` (no screenshots there). FETCHED
- (d) docs: get_python_api_docs(identifier:str) (fully-qualified name; "*" and "X.*" discovery), search_api_docs(query, max_results=20, context=0, index=None), search_manual_docs (same shape). Offline: bundled RST of bpy/bmesh/mathutils/gpu/ops plus the manual in mcp/blmcp/data/. FETCHED
- Claude Code config: no Claude-Code-specific page; wiki pages are Home, Llama.cpp, Setup. Setup page gives stdio config (after `git clone` to C:\blender_mcp):
{"mcpServers":{"blender":{"command":"uv","args":["--directory","C:\\blender_mcp\\mcp","run","blender-mcp"]}}} FETCHED
Claude Code equivalent would be `claude mcp add blender -- uv --directory C:\blender_mcp\mcp run blender-mcp`. KNOWLEDGE (derived, not tested). README also lists `pip install git+https://projects.blender.org/lab/blender_mcp.git#subdirectory=mcp`. FETCHED
- Windows / issue #24: "Blender_mcp Connector/extension install fails on Windows..." opened 2026-04-29 by Warren-Postma, state OPEN today. Failure: Claude Desktop (MSIX build) runs `uv run blender-mcp` on the extension folder; editable setuptools build fails with "egg_base '.' does not exist". Maintainer dfelinto: cannot reproduce with website-downloaded Claude Desktop, did not try the Store build; refers reporter to Anthropic; rejects a `python -m` workaround (needs one command that installs deps and runs). Reporter: pipx install works around the egg_info error. FETCHED (API issues/24 + comments). Concerns the Desktop .mcpb path; the wiki `uv --directory` path was not reported broken there.
## B. Community BlenderMCP (github.com/ahujasid/blender-mcp, package now "mcp-for-blender")
- Version: pyproject 2.1.9; last commit/push 2026-10-06; ~30.3k stars; GitHub tags/releases API returned none. Licence MIT. FETCHED. Add-on minimum Blender (3,0,0). FETCHED (addon.py L34)
- Self-described "not affiliated with Blender Foundation". Telemetry exists (disable_telemetry tool; README "Telemetry Control"). FETCHED
- Tools (server.py @mcp.tool): get_addon_status, disable_telemetry, get_scene_info, look, execute_blender_code, record_trajectory_feedback, generate_3d, search_assets, import_asset; app-only: search_mentions, open_viewport, viewport_latest, viewport_capture(max_size=1000), viewport_pick(seq,x,y). FETCHED. (Older get_viewport_screenshot is not in this list; `look` took its place.)
- (a) look(mode=viewport|camera|angles|frames, target, views, distance, shading=solid|material|rendered|wireframe|xray, frames, frame_count=6, view, image, max_size=768, user_prompt) -> image; restores changed settings. FETCHED (docstring). Clamp 200-2000 on scripted path comes from a WebFetch summary of server.py: SEARCH-grade.
- (b) selection: get_scene_info(query, root, fields, limit=20) header line carries active, selected (names, capped), mode; per-object fields location/size/children/hidden etc. No vertex/face selection tool; use execute_blender_code. FETCHED
- (c) execute_blender_code(code, user_prompt="") -> text of printed output; full bpy/bmesh/mathutils. FETCHED
- (d) API docs lookup: none in the tool list. FETCHED (absence)
- Safe mode: env BLENDER_MCP_SAFE_MODE=1 validates scripts before running, in execute_blender_code only. Allows imports of bpy, bmesh, mathutils and pure-python stdlib; render/save/import/export operators allowed. Blocks eval/exec/open, os/subprocess/network, handlers/timers/drivers, class/property registration, loading external .blend datablocks. Rejection text says only the user can disable it. Default OFF. FETCHED (server.py L788-815, README L397)
- Socket: add-on binds host default 'localhost', port 9876 (addon.py L1184, L1281); no auth found by grep. FETCHED
- Claude Code: `claude mcp add blender uvx mcp-for-blender`; install.ps1/install.sh detect Claude Code. FETCHED (README L105, L428)
## C. Blender Agent (projects.blender.org/Rich-Siomporas/blender-agent)
- Fork of the official lab repo by Rich-Siomporas, 0 stars, updated 2026-09-30. README: adds web-UI agent harness, MCP over streamable HTTP, OpenAI-compatible /v1/chat/completions, skills tools (skills_list/search/read, welcome), mcp_ext rig + media_io extensions, Docker/Helm. States core MCP tool surface and add-on are upstream's. FETCHED
- readme_tools.rst grep returned no tool lines (format differs); README L305-306 lists upstream navigation/render tools. No vertex-selection or Edit Mode tool seen in README grep; tool code not read. FETCHED (partial)
- README contradiction: BLENDER_AGENT_HOST default 0.0.0.0 (L247) vs "endpoint binds loop-back" (L198). FETCHED