ellmos Blender Use MCP

🇩🇪 Deutsche Version

Part of the ellmos-ai family and the open-bricks open-source initiative.

npm downloads Verified Last-checked Contributing: Guide Level 1 SBOM

Quick Navigation

Language / Sprache: 🇬🇧 English | 🇩🇪 Deutsch

1. Key Capabilities

An asset-QA tool for game and 3D asset pipelines: verify that an exported FBX actually reimports cleanly in headless Blender — mesh count, material count, and required naming prefixes checked automatically, with a deterministic JSON result instead of a manual eyeball pass. blender_verify_fbx_reimport is the core structural tool and blender_verify_visual its visual counterpart — the first counts meshes and checks name prefixes, the second renders four views and measures geometry that counting cannot see. blender_locate and blender_run_script are the general-purpose primitives both are built on.

No add-on. No TCP port. No background daemon. This server does not install anything into Blender, does not open a socket for a running Blender instance to connect to, and does not keep Blender resident. Each call spawns blender --background --python <script.py>, waits for a bounded, timeout-guarded exit, and returns the result — headless and stateless by design. It does not download assets and does not collect telemetry.

How this differs from other Blender MCP servers. Most Blender MCP projects (e.g. ahujasid/blender-mcp, the official Blender Labs MCP server) drive a live, running Blender GUI over a TCP/add-on bridge for interactive scene editing — a different use case with a different trust model (an open socket, an installed add-on, a persistent process). This server instead targets CI-style, one-shot asset verification: run it in a pipeline step, get a pass/fail JSON, move on. If you need live GUI control, use a reviewed Blender MCP add-on separately (see Safety below).

2. Target Personas & High-Intent Discoverability

[PERSONA-01] Indie & AAA Game Technical Artists & 3D Pipeline TDs

• Profile: Technical Artists managing FBX/GLTF asset pipelines for Unreal Engine, Unity, Godot, and custom C++ game engines.
• Pain Point: Exported 3D assets frequently have unapplied rotation (lying on their side in-engine), broken pivot offsets, missing SM_/M_ prefixes, or unassigned materials that slip past manual review.
• High-Intent Queries: blender fbx reimport verification mcp, blender headless asset qa gate, automated fbx naming convention check, detect unapplied rotation fbx blender.
• How We Solve It: One-shot structural reimport verification and 4-view visual geometry checks without having to open the Blender GUI.

[PERSONA-02] CI/CD Automation & Build Infrastructure Engineers

• Profile: DevOps and Build Engineers responsible for automated asset validation gates in GitHub Actions, GitLab CI, or Jenkins.
• Pain Point: Traditional Blender automation tools require installing graphical add-ons or running interactive background sockets, which fail in headless containerized runners.
• High-Intent Queries: headless blender asset qa mcp server, github actions blender fbx qa gate, blender background script ci cd verification, blender mcp no add-on no tcp port.
• How We Solve It: Stateless blender --background execution with strict 15-minute runaway timeouts, bounded 8 KB memory tails, zero add-ons, and deterministic JSON exit codes.

[PERSONA-03] Autonomous AI Agent Engineers (Claude, Codex, Gemini)

• Profile: Developers deploying autonomous AI coding agents for procedural 3D generation, asset processing, and game prototyping.
• Pain Point: AI agents need to inspect and verify 3D assets without socket leaks, zombie processes, or uncontrolled memory consumption.
• High-Intent Queries: mcp server fbx mesh material verification, ai agent blender 3d asset inspection, blender four-view rendering mcp, llm tool headless blender.
• How We Solve It: Native Model Context Protocol (MCP) server with comprehensive llms.txt documentation, robust taskkill /T /F process tree termination, and fail-closed temporary file cleanup.

[PERSONA-04] Enterprise Game Studio Compliance & Security Officers

• Profile: Security Officers and Compliance Managers safeguarding proprietary game IP and development workstations.
• Pain Point: Third-party DCC tools frequently open local network ports, dial remote telemetry servers, or require administrator privileges.
• High-Intent Queries: offline blender mcp zero egress, air gapped 3d asset verification, unprivileged blender asset qa, zero copyleft mcp tool.
• How We Solve It: Strict RunAsInvoker non-elevation certification, 100% offline zero-egress guarantee, zero runtime telemetry, and Level 1 SBOM with 0% copyleft licenses.

3. 10-Dimension Comparative Matrix vs. Alternatives

4. Architecture & Component Topology

ASCII Four-View Architectural Topology

+--------------------------------------------------------------------------------------------------+
|                               ELLMOS BLENDER USE MCP ARCHITECTURAL TOPOLOGY                      |
+--------------------------------------------------------------------------------------------------+
| [VIEW 1: CALLER RUNTIMES & AGENT CLIENTS]                                                        |
|   * Autonomous Agents   : Claude Code, OpenAI Codex, Antigravity / Gemini, Kimi, Cursor          |
|   * Transport Protocols : Model Context Protocol (MCP stdio), JSON-RPC 2.0 framing               |
|   * Automation Entry    : npx -y ellmos-blender-use-mcp, CI/CD runners, local development shells |
|   * Tool Surface        : blender_verify_fbx_reimport, blender_verify_visual,                      |
|                           blender_run_script, blender_locate                                     |
+--------------------------------------------------------------------------------------------------+
|                                                |                                                 |
|                                                v                                                 |
+--------------------------------------------------------------------------------------------------+
| [VIEW 2: BLENDER USE MCP CORE ENGINE & DISCOVERY ORCHESTRATOR]                                   |
|   * Protocol Dispatch   : ESM stdio router with Zod schema validation & parameter checking       |
|   * Executable Resolver : Windows Registry / BLENDER_EXE / Program Files / PATH auto-discovery   |
|   * Bounded Supervision : 8 KB default tail buffer, 50 KB ceiling, hard child process kill tree  |
|   * Script Synthesizer  : Dynamic ephemeral Python QA script generation with fail-closed purge   |
+--------------------------------------------------------------------------------------------------+
|                                                |                                                 |
|                                                v                                                 |
+--------------------------------------------------------------------------------------------------+
| [VIEW 3: RUNTIME PERSISTENCE, VISUAL ASSET REPORTS & EPHEMERAL SCRIPTS]                          |
|   * Structural QA       : Headless FBX import, mesh/empty enumeration, material slot assignment  |
|   * Visual 4-View Engine: Orthogonal front, side, top & perspective rendering pipeline           |
|   * Anomaly Detectors   : Unapplied rotation, floating meshes, displaced origin/pivot, residuals |
|   * Deterministic Output: JSON test receipts with structured metrics, pass/fail status & counts  |
+--------------------------------------------------------------------------------------------------+
|                                                |                                                 |
|                                                v                                                 |
+--------------------------------------------------------------------------------------------------+
| [VIEW 4: AIR-GAP DEFENSE PERIMETER, RUNASINVOKER & ZERO-EGRESS]                                  |
|   * Security Model      : RunAsInvoker unprivileged execution (Zero administrative elevation)    |
|   * Network Isolation   : 100% Zero-Egress, zero telemetry, air-gapped offline operation         |
|   * Lifecycle Governance: Stateless execution (no resident daemon, no add-on mutation, no TCP)   |
|   * Supply Chain        : Level 1 SBOM, 100% permissive runtime (MIT/BSD), 48h Security SLA      |
+--------------------------------------------------------------------------------------------------+

Component Flow Diagram

graph TD
    subgraph Client ["AI Assistant & Client Environment"]
        AI["AI Agent (Claude / Codex / Gemini)"]
        Config["MCP Configuration (npx / node)"]
    end

    subgraph Server ["ellmos Blender Use MCP Server"]
        MCP["MCP Protocol Server (src/index.js)"]
        subgraph Tools ["Tool Handlers"]
            T1["blender_verify_fbx_reimport"]
            T2["blender_run_script"]
            T3["blender_locate"]
            T4["blender_verify_visual"]
        end
        Safety["Timeout & Tail Buffer Guard (8k chars)"]
    end

    subgraph Subprocess ["Headless Subprocess (Isolated)"]
        Exe["Blender Executable (blender --background)"]
        Python["Temp Python Verification Script"]
        FBX["Target FBX Asset File"]
        JSONOut["Deterministic JSON Result"]
    end

    AI -->|JSON-RPC Request| MCP
    MCP --> Tools
    T1 -->|Generates script & spawns| Exe
    T2 -->|Executes arbitrary python| Exe
    T3 -->|Locates binary| Exe
    T4 -->|Generates visual verification script & spawns| Exe
    Exe --> Python
    Python --> FBX
    FBX -->|Mesh / Material / Naming QA| JSONOut
    JSONOut --> Safety
    Safety -->|Bounded Response| AI

    style Client fill:#1e1e2e,stroke:#89b4fa,stroke-width:1px
    style Server fill:#181825,stroke:#cba6f7,stroke-width:1px
    style Subprocess fill:#11111b,stroke:#a6e3a1,stroke-width:1px

5. Headless Asset-QA Verification Lifecycle

sequenceDiagram
    autonumber
    actor Client as AI Assistant / CI Pipeline
    participant Server as ellmos Blender Use MCP
    participant Resolver as Blender Resolver
    participant Process as Headless Subprocess
    participant Python as Blender Python Engine
    participant FS as Local Filesystem (FBX)

    Client->>Server: Call blender_verify_fbx_reimport(fbxPath, requiredPrefixes)
    Server->>Resolver: Resolve Blender Executable (blender_locate / BLENDER_EXE / Registry / PATH)
    Resolver-->>Server: Return Validated Executable Path
    Server->>FS: Write Temp Python Verification Script
    Server->>Process: Spawn blender --background --python script (timeout-guarded)
    Process->>Python: Execute Verification Script
    Python->>FS: bpy.ops.import_scene.fbx(filepath=fbxPath)
    FS-->>Python: Parse Mesh Objects & Material Slots
    Python->>Python: Validate Naming Prefixes, Object Counts & Hierarchy
    Python->>FS: Write Output JSON Verification Result
    Process-->>Server: Process Exit (Exit Code 0 / Bounded Tail Buffer)
    Server->>FS: Read Result & Clean Up Temp Verification Script
    Server-->>Client: Deterministic JSON Result (meshCount, materialCount, missingPrefixes, ok)

6. Tool Suite & Verification Matrix

7. blender_verify_fbx_reimport Deep Dive & Schema

Imports an FBX file into headless Blender and verifies mesh count, empty count, material count, material slot assignments, and required naming prefixes.

Parameters

Example Invocation

{
  "fbxPath": "assets/models/SM_Watchtower_01.fbx",
  "requiredPrefixes": ["SM_", "M_"]
}

Deterministic Output Schema

{
  "ok": true,
  "blender": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe",
  "fbxPath": "C:\\projects\\game\\assets\\models\\SM_Watchtower_01.fbx",
  "resultPath": "C:\\projects\\game\\assets\\models\\verify_reimport_result.json",
  "exitCode": 0,
  "timedOut": false,
  "durationMs": 1820,
  "outputTruncated": false,
  "verification": {
    "ok": true,
    "fbx": "C:\\projects\\game\\assets\\models\\SM_Watchtower_01.fbx",
    "mesh_count": 3,
    "empty_count": 0,
    "material_count": 2,
    "materials": [
      "M_Stone_Brick",
      "M_Wood_Trim"
    ],
    "missing_prefixes": [],
    "script_free": true
  }
}

8. Visual Verification Deep Dive & 4-View Geometry

Renders four views of an FBX and checks geometry that a structural reimport cannot see.

blender_verify_fbx_reimport counts meshes and checks name prefixes — it cannot tell you that a mesh is lying on its side, that a part floats away from the assembly, or that the pivot sits outside the model. This tool does, and it produces the renders to look at.

{ "fbxPath": "kit.fbx", "outDir": "verify_visual", "expectHeight": "2.5,3.5" }

Four-View Orthogonal Projection & Failure Detection

+---------------------------------------+---------------------------------------+
|              TOP VIEW                 |           PERSPECTIVE VIEW            |
|              (XY Plane)               |              (Isometric)              |
|                                       |                                       |
|   Detects: X/Y planar alignment,      |   Detects: Overall silhouette,        |
|   bounding box symmetry, footprint    |   complex assembly integration        |
+---------------------------------------+---------------------------------------+
|             FRONT VIEW                |               SIDE VIEW               |
|              (XZ Plane)               |              (YZ Plane)               |
|                                       |                                       |
|   Detects: Model height, Z-grounding, |   Detects: Depth errors, floating vs  |
|   upright orientation (lying down)    |   resting parts, pivot offset         |
+---------------------------------------+---------------------------------------+

Detected failure classes: unapplied rotation, floating parts in multi-part assets, pivot/origin outside the bounding box, transform residuals in the export, stray empties.

Deterministic Output Schema

{
  "ok": true,
  "blender": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe",
  "fbxPath": "C:\\projects\\game\\kit.fbx",
  "outDir": "C:\\projects\\game\\verify_visual",
  "exitCode": 0,
  "timedOut": false,
  "durationMs": 3450,
  "outputTruncated": false,
  "verification": {
    "ok": true,
    "fails": [],
    "warns": [],
    "metrics": {
      "dimensions": [2.45, 1.82, 4.10],
      "center": [0.0, 0.0, 2.05],
      "pivotAtOrigin": true,
      "unappliedRotation": false
    }
  },
  "renders": {
    "view_front": "verify_visual/view_front.png",
    "view_side": "verify_visual/view_side.png",
    "view_top": "verify_visual/view_top.png",
    "view_perspective": "verify_visual/view_perspective.png"
  }
}

Why four views and not one: a single front shot hides depth errors — floating-vs-resting, behind-vs-in-front. A real case: chain links looked correctly attached from the front and were not attached at all when seen from the side.

Like every tool here it is a one-shot headless run: no add-on, no daemon, no socket.

9. General-Purpose Primitives (blender_locate & blender_run_script)

• blender_locate: Resolves the active Blender executable on Windows, Linux, or macOS across explicit call parameters, environment variable BLENDER_EXE, standard installation paths (newest version first), and system PATH.
• blender_run_script: Runs an arbitrary local Python script via blender --background --python <script.py> with optional arguments, timeout guardrail, and hard tail-buffer truncation (8 KB default, up to 50 KB max).

10. CI/CD Pipeline Integration (GitHub Actions)

Integrate headless asset QA directly into your GitHub Actions pull request checks to prevent broken FBX models, missing material slots, unapplied rotations, and displaced pivots from reaching the main branch:

name: 3D Asset QA Gate

on:
  pull_request:
    paths:
      - "assets/**/*.fbx"

jobs:
  verify-assets:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Install Blender & Node.js
        run: |
          sudo snap install blender --classic
          sudo apt-get install -y nodejs npm

      - name: Run Headless Asset Verification
        run: |
          npx -y ellmos-blender-use-mcp --version
          # Run structural FBX QA and 4-view visual verification
          blender --background --factory-startup --python node_modules/ellmos-blender-use-mcp/scripts/verify_asset_visual.py -- \
            --fbx assets/models/SM_HeroAsset.fbx \
            --out build/asset-qa/ \
            --json

11. Governance & Runtime Invariants

The server enforces 10 architectural and runtime invariants to guarantee privacy, safety, process isolation, and auditability:

12. Security Policy & RunAsInvoker

• Local Python Execution: This server runs local Python inside Blender. Use only scripts and asset paths you trust.
• RunAsInvoker Non-Elevation: Runs strictly under standard unprivileged user accounts; no administrator or root privileges required.
• Process Cleanup: Subprocesses are supervised; Windows processes are cleanly killed via taskkill /pid <PID> /T /F on timeout.
• Offline Assurance: No remote asset marketplaces, external APIs, or usage telemetry are involved.
• Vulnerability Disclosure: Review SECURITY.md for official coordination contacts and our binding 48-hour response SLA.

13. Installation & Getting Started

Option 1: Run via npx (no install)

{
  "mcpServers": {
    "blender-use": {
      "command": "npx",
      "args": ["-y", "ellmos-blender-use-mcp"]
    }
  }
}

Option 2: Install from source

git clone https://github.com/ellmos-ai/ellmos-blender-use-mcp.git
cd ellmos-blender-use-mcp
npm install
npm run build
node src/index.js

For a local checkout, point command/args at the cloned src/index.js instead:

{
  "mcpServers": {
    "blender-use": {
      "command": "node",
      "args": ["<path-to-repo>/src/index.js"]
    }
  }
}

14. Configuration & Environment

• BLENDER_EXE — optional path to the Blender executable. Without it, tools try the explicit blenderPath argument, then BLENDER_EXE, then standard Blender install locations on Windows (%ProgramFiles%\Blender Foundation\Blender <version>\blender.exe and equivalent 32-bit and per-user roots, newest version first), then PATH. On Linux and macOS the lookup goes straight from BLENDER_EXE to PATH.
• Every tool also accepts an explicit blenderPath argument per call, which takes priority over BLENDER_EXE.
• Process output is retained only as a tail: blender_run_script defaults to 8,000 characters (configurable up to 50,000); FBX verification keeps 8,000. The response marks outputTruncated: true when earlier output was discarded, so verbose Blender scripts cannot grow the MCP process memory without bound.

15. Third-Party Licenses & Level 1 SBOM

All runtime production dependencies are distributed under permissive open-source licenses (MIT and BSD-2-Clause) with 0% copyleft:

• @modelcontextprotocol/sdk (MIT)
• update-notifier (BSD-2-Clause)
• zod (MIT)

For the complete dependency inventory, Invariant Cross-Reference Matrix, and prior-art isolation analysis, see THIRD_PARTY_LICENSES.md and the companion plaintext inventory THIRD_PARTY_LICENSES.txt.

16. Sibling Projects & ellmos-ai Ecosystem

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.

MCP Server Family

AI Infrastructure & Developer Tools

Desktop Software Suite & Sibling Tools

Our partner organization open-bricks bundles AI-native desktop applications and developer utilities — a modern, open-source software suite built for the age of AI:

17. LLM Context Index (llms.txt)

For AI assistants and LLM tooling, llms.txt provides machine-readable architecture documentation, tool descriptions, search phrases, and runtime invariants.

18. License & Statutory Disclaimer (§ 521 BGB)

License & Attribution

Distributed under the MIT License. See LICENSE and NOTICE for full copyright and attribution details.

Statutory German Disclaimer (§ 521 BGB Gefälligkeitsrecht)

This open-source package is provided free of charge without consideration (Gefälligkeit). Under statutory German law (§ 521 BGB), liability for defects in quality and title is strictly limited to intentional misconduct (Vorsatz) and gross negligence (grobe Fahrlässigkeit).

Security Response Commitment

Security vulnerabilities are triaged within 48 hours under our binding Security SLA. Refer to SECURITY.md for coordinated disclosure guidelines.