Skip to content
Back to search

blender-mcp

Independent enhanced distribution of Blender Lab MCP: standalone bpy, runtime API documentation, and benchmark tooling

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bpy-dev/blender-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bpy-dev/blender-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bpy-dev--blender-mcp/badge.svg)](/listings/bpy-dev--blender-mcp)

HTML

<a href="/listings/bpy-dev--blender-mcp"><img src="/api/listings/bpy-dev--blender-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readme.md · README · 146 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Blender MCP
  2. ## Enhanced MCP developer preview
  3. This branch packages an enhanced Blender MCP workflow for agentic Blender work. It keeps the upstream live Blender add-on/server model and adds saved-file/headless execution, selectable command-line backends, runtime Blender Python API lookup, subprocess/capture hardening, and benchmark tooling.
  4. This is a modified distribution of Blender Lab's Blender MCP project. See [NOTICE.md](NOTICE.md) for provenance and [SECURITY.md](SECURITY.md) for the execution-risk model. Public `bpy.dev` website assets will live in a separate repository.
  5. ### BlenderBench result
  6. [![BlenderBench result](https://bpy.dev/assets/blenderbench-result.webp)](https://huggingface.co/datasets/michaelgold/blenderbench-direct-results/resolve/7c2c43be4517aee4d76d2b445578988de186970c/video/blenderbench-complete-compilation.mp4)
  7. The compilation covers **27 tasks / 270 rounds**. Its on-video “CLIP accuracy” label means
  8. **CLIP image-embedding cosine similarity, not literal accuracy**. The linked immutable
  9. H.264 video is 848×464, 134.9 seconds, and 10,161,884 bytes; SHA-256:
  10. `04966320de680203baed6c01c3e211059350454139dc8a802c557cce24815c17`.
  11. ### What is enhanced
  12. - **Saved-file tools:** `_for_cli` tools operate on `.blend` files in fresh subprocesses without requiring a live Blender UI session.
  13. - **Local CPU previews:** the additive capped preview tool supports saved-file agent edit/save/fork workflows without CUDA; see [local milestone status and acceptance](docs/local-preview.md). Existing CUDA benchmark rendering is unchanged.
  14. - **Backend selection:** use a Blender executable backend or a standalone `bpy` Python backend with `BLENDER_MCP_CLI_BACKEND`.
  15. - **Runtime API lookup:** agents can query exact signatures, enums, defaults, and availability from the active Blender/`bpy` runtime instead of relying only on bundled docs.
  16. - **Process isolation:** command-line executions are bounded by explicit timeouts, output caps, compact JSON framing, and source-file overwrite checks. This is crash/process-state isolation, not an OS sandbox.
  17. - **Benchmark tooling:** deterministic token-efficiency tasks, exploratory creative comparison harnesses, and a [portable model-neutral full-27 BlenderBench runner](benchmarks/blenderbench_direct/README.md) with pinned inputs and post-generation scoring.
  18. ### Current publication status
  19. Developer-preview cleanup is in progress. Before publishing, complete [PUBLICATION_CHECKLIST.md](PUBLICATION_CHECKLIST.md), especially package naming, fresh-clone install smoke tests, and tracked-file secret scanning.
  20. ## Overview
  21. A lightweight MCP (Model Context Protocol) server for Blender.
  22. It offers a natural language interface with Blender's Python API,
  23. improving access to documentation, and allowing users to explore
  24. and understand complex setups.
  25. Read the documentation at [blender.org/lab/mcp-server](https://www.blender.org/lab/mcp-server/)
  26. ----
  27. The project is deliberately small, maintainable, and does no more than
  28. necessary. It has two components that communicate over a TCP socket:
  29. - A **Blender add-on** that runs inside Blender and executes live-scene requests.
  30. - An **MCP server** that runs as a separate process, launched by the
  31. MCP client (e.g. [Llama.cpp](https://projects.blender.org/lab/blender_mcp/wiki/Llama.cpp)).
  32. The data flow is:
  33. ```
  34. MCP Client ⇐ MCP/stdio ⇒ blender-mcp ⇐ TCP socket ⇒ Blender Add-on
  35. ```
  36. ## Blender Add-on
  37. Located in ``addon/blender_mcp_addon/``.
  38. A Blender extension that allows the MCP server to communicate with a
  39. running Blender instance. It must be installed and enabled for connected
  40. live-scene tools; saved-file ``_for_cli`` tools run without it.
  41. The add-on provides a preferences panel for configuring the host, port,
  42. and an optional auto-start setting.
  43. ### Functionality Overview
  44. Note that this is intended to be a fairly minimal add-on.
  45. Connectivity
  46. - Auto-start (optional), is non-blocking any issues can be viewed from the preferences.
  47. - Configurable polling intervals (active and idle rates) from preferences to avoid excessive overhead.
  48. - Client timeout protection - stalled connections are evicted.
  49. - Start/stop operators accessible from the preferences panel.
  50. - Deferred responses are supported only by the interactive add-on server;
  51. background mode requires requests to complete synchronously and rejects deferred results.
  52. ## MCP Server
  53. Located in ``mcp/blmcp/``, installed as a Python package with the
  54. entry point ``blender-mcp``.
  55. An MCP client launches this process and communicates with it over
  56. stdio. The server connects to the add-on's TCP socket to relay
  57. requests to Blender.
  58. ``mcp/blmcp/data/``
  59. Data files bundled with the package.
  60. - ``prompts.yml`` provides instructions sent to the LLM at
  61. connection time.
  62. - ``api/`` contains Blender Python API reference in RST format.
  63. - ``manual/`` contains Blender user manual excerpts in RST format.
  64. ``mcp/blmcp/tools/``
  65. Each tool is a single module, auto-discovered at startup.
  66. Modules ending in ``_toolcode`` contain code that runs inside
  67. Blender (sent to the add-on for execution) and are skipped during
  68. discovery.
  69. ``mcp/blmcp/tools_helpers/``
  70. Shared utilities used by tools. Tools should not import from each
  71. other; shared logic lives here instead.
  72. ### Command-line Backends
  73. Tools whose names end in ``_for_cli`` open a saved ``.blend`` file in a fresh
  74. subprocess. They use the Blender executable by default, or a standalone
  75. ``bpy`` Python when selected with environment variables. Live tools such as
  76. ``execute_blender_code`` still use the add-on and the open Blender session.
  77. This native MCP client configuration launches the server with the standalone
  78. backend. Replace both absolute placeholders for your installation:
  79. ```json
  80. {
  81. "mcpServers": {
  82. "blender": {
  83. "command": "uv",
  84. "args": [
  85. "--directory",
  86. "/absolute/path/to/blender_mcp/mcp",
  87. "run",
  88. "blender-mcp"
  89. ],
  90. "env": {
  91. "BLENDER_MCP_CLI_BACKEND": "bpy",
  92. "BLENDER_MCP_BPY_PYTHON": "/absolute/path/to/python-with-bpy"
  93. }
  94. }
  95. }
  96. }
  97. ```
  98. See [Command-line Blender and standalone bpy backends](readme_bpy_backend.rst)
  99. for installation, compatibility, runtime boundaries, troubleshooting, and
  100. security guidance.
  101. ### Tools
  102. See [readme_tools.rst](readme_tools.rst) for the tools the MCP server exposes.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.