# ellmos Blender Use MCP
**🇩🇪 [Deutsche Version](README_de.md)**
*Part of the [ellmos-ai](https://github.com/ellmos-ai) family and the [open-bricks](https://github.com/open-bricks) open-source initiative.*
[](https://www.npmjs.com/package/ellmos-blender-use-mcp)
[](https://www.npmjs.com/package/ellmos-blender-use-mcp)
[](https://github.com/ellmos-ai/ellmos-blender-use-mcp/actions/workflows/ci.yml)
[](test/)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://github.com/ellmos-ai/ellmos-blender-use-mcp)
[](SECURITY.md)
[](SECURITY.md)
[](SECURITY.md)
[](package.json)
[](llms.txt)
[](https://glama.ai/mcp/servers/@ellmos-ai/ellmos-blender-use-mcp)
[](https://github.com/ellmos-ai)
[](https://github.com/open-bricks)
[](llms.txt)
---
### Quick Navigation
> **Language / Sprache:** 🇬🇧 **English** | 🇩🇪 **[Deutsch](README_de.md)**
[1. Key Capabilities](#key-capabilities) • [2. Architecture & Component Topology](#architecture--workflow) • [3. Headless Verification Lifecycle](#2-headless-asset-qa-verification-lifecycle) • [4. Tool Suite & Verification Matrix](#tools) • [5. Visual Verification Deep Dive](#blender_verify_visual) • [6. CI/CD Integration](#cicd-pipeline-integration) • [7. Governance & Runtime Invariants](#governance--runtime-invariants) • [8. Security Policy](SECURITY.md) • [9. Installation & Setup](#installation) • [10. Configuration & Environment](#configuration) • [11. Third-Party Licenses](THIRD_PARTY_LICENSES.md) • [12. Sibling Projects & Ecosystem](#ellmos-ai-ecosystem) • [13. LLM Context](llms.txt) • [14. Changelog](CHANGELOG.md) • [15. License & Copyright](#license)
---
## 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 `, 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](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
```mermaid
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
```
### 2. Headless Asset-QA Verification Lifecycle
```mermaid
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