ellmos Blender Use MCP

🇩🇪 Deutsche Version

Part of the ellmos-ai family.

📦 View on npm → | 🛡️ Security Policy | 🤖 LLM Context | 🌐 Ecosystem

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).

Note

AI / LLM Integration & Machine-Readable Context: AI assistants (Claude, Codex, Gemini) can read llms.txt for machine-readable context, search phrases, and tool documentation. Regression test suites guard privacy hygiene and runtime memory safety.

Tip

CI & Asset Pipeline Automation: Use blender_verify_fbx_reimport as an automated gate before committing 3D assets to source control. It flags missing prefixes (e.g., SM_, M_), unexpected mesh counts, or broken material assignments without human intervention.

Architecture & Workflow

1. Component Topology

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
    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

Loading

2. 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)

Loading

Tools

Tool	Purpose
blender_verify_fbx_reimport	Generate a temporary Blender verification script, import an FBX, and write a JSON result with mesh/material counts and missing required prefixes.
blender_run_script	Run blender --background --python <script.py> with optional arguments and bounded stdout tail.
blender_locate	Resolve the Blender executable from an explicit path, BLENDER_EXE, the standard Windows install locations, or PATH.
blender_verify_visual	Render four views of an FBX and check geometry a structural reimport cannot see: unapplied rotation, floating parts, pivot outside the model, transform residuals, stray empties.

blender_verify_visual

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" }

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

Returns verification (the parsed verify_visual_result.json with ok, fails, warns, metrics) plus renders — view_front.png, view_side.png, view_top.png, 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.

Safety

• This server runs local Python inside Blender. Use only scripts and asset paths you trust.
• The default timeout is bounded.
• No remote asset marketplaces, API keys, or telemetry are included.
• For live GUI control, use a reviewed Blender MCP add-on separately.

Installation

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"]
    }
  }
}

Configuration

• BLENDER_EXE — optional path to the Blender executable. Without it, tools try the explicit blenderPath argument, then BLENDER_EXE, then the standard Blender install locations on Windows (%ProgramFiles%\Blender Foundation\Blender <version>\blender.exe and the 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.

License

MIT — see LICENSE.

---

ellmos-ai Ecosystem

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

MCP Server Family

Server	Tools	Focus	npm
FileCommander	46	Filesystem, process management, interactive sessions, cloud-lock-safe operations	ellmos-filecommander-mcp
CodeCommander	22	Code analysis, JSON repair, imports, diffs, regex	ellmos-codecommander-mcp
Clatcher	12	File repair, format conversion, batch operations	ellmos-clatcher-mcp
n8n Manager	18	n8n workflow management via AI assistants	n8n-manager-mcp
ControlCenter	20	MCP stack discovery, profile management, control plane	ellmos-controlcenter-mcp
Homebase	45	Local-first LLM memory, knowledge, state, routing, swarm orchestration	ellmos-homebase-mcp (alpha)
ServerCommander	8	Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics	ellmos-servercommander-mcp (alpha)
Blender Use	3	Headless Blender asset QA and FBX reimport verification	ellmos-blender-use-mcp (alpha)
Open Compute	10	Model-agnostic computer use: capture, safety-gated actions, Windows UIA	open-compute-mcp (alpha)

AI Infrastructure & Developer Tools

Project	Description
workflowhooker	Transparent command interceptor & safety sandbox for agentic workflows
system-explorer	System inspection, MCP orchestration, and fleet introspection runtime
memoryhooker	High-performance episodic memory interceptor for AI agents
policy-registry	Policy distribution and compliance engine for multi-agent frameworks
ellmos-delegation-authority	Trust boundary verification & cryptographic token delegation authority
sqlite-transit-sync	Transactional SQLite transit replication with snapshot isolation
BACH	Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory
open-compute	Model-agnostic computer-use core powering Open Compute MCP
clutch	Provider-neutral LLM orchestration with auto-routing and budget tracking
rinnsal	Lightweight agent memory, connectors, and automation infrastructure
ellmos-stack	Self-hosted AI research stack (Ollama + n8n + Rinnsal + KnowledgeDigest)
MarbleRun	Autonomous agent chain framework for Claude Code
gardener	Minimalist database-driven LLM OS prototype (4 functions, 1 table)
ellmos-tests	Testing framework for LLM operating systems (7 dimensions)

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:

Project	Ecosystem	Description
ProFiler	file-bricks	Advanced file management, deep inspection, and batch pipeline workbench
DokuZen	doc-bricks	Unified document converter, markdown formatter, and documentation hub
PDFtoPDFocr	doc-bricks	High-fidelity OCR processor and searchable PDF pipeline
MediaBrain	file-bricks	AI-assisted media categorization, tagging, and asset management
TextBrain	doc-bricks	Text analysis, summarization, and local language intelligence suite
knowledgedigest	open-bricks	Knowledge extraction, semantic clustering, and synthesis engine
DevCenter	dev-bricks	Developer environment orchestration and multi-agent management cockpit
CodeBox	dev-bricks	Secure execution sandbox and isolated code-runner runtime