blender-mcp-master
# Blender MCP Master
<p align="center">
<strong>Model with intent. Verify with evidence.</strong><br>
An open-source Agent Skill for Blender workflows.
</p>
<p align="center">
<a href="https://github.com/God-601/blender-mcp-master/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/God-601/blender-mcp-master?include_prereleases&style=flat-square&label=release"></a>
<a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-21262d?style=flat-square"></a>
<a href="https://github.com/God-601/blender-mcp-master/actions/workflows/static-checks.yml"><img alt="GitHub Actions" src="https://img.shields.io/badge/CI-GitHub_Actions-21262d?style=flat-square"></a>
</p>
<p align="center">
<a href="#get-started">Get started</a> ·
<a href="#workflow">Workflow</a> ·
<a href="#documentation">Documentation</a> ·
<a href="#portugues">Português</a>
</p>
---
<p align="center"><img src="assets/banner.svg" width="100%" alt="Concept illustration: isometric mesh study representing Blender MCP Master, not an actual generated Blender model"></p>
### Better decisions. Better meshes.
Blender MCP Master helps AI agents **plan, model, inspect, and validate** Blender assets using task-specific instructions, scripts, and evidence-based quality checks.
> **Important:** This skill does **not** control Blender by itself. Live editing needs a separate Blender-control MCP server and Blender addon. The optional MCP resource server here is *read-only*.
**Blender MCP Master 2.0:** seven reusable specialist modules, executable
host-adapter orchestration, independent QA handoffs, hashed evidence receipts
and default dry-run. A concrete Codex CLI worker handles read-only reviews;
the bundled native bpy host supplies checkpoints, scene probes, writer leases
and dispatch of explicitly inspected production callbacks.
[Execution contract](references/specialist-orchestration.md) ·
[Implementation and Agency Agents references](docs/V2-IMPLEMENTATION.md) ·
[Validation record](docs/V2-EVIDENCE.md).
See the [2.0 release notes](docs/release-notes-2.0.md) for migration and
the scope of verified behavior.
| Define | Build | Inspect | Deliver |
| :--- | :--- | :--- | :--- |
| Establish style, purpose, proportions, and constraints. | Block out primary forms, then refine in reversible stages. | Verify actual mesh data and visual references. | Disclose measured results and what remains unverified. |
## Get started
**1. Install the stable skill**
**[Download v2.0.0 · Installable ZIP](https://github.com/God-601/blender-mcp-master/releases/download/v2.0.0/blender-mcp-master-2.0.0.zip)**
Get [SHA256SUMS.txt](https://github.com/God-601/blender-mcp-master/releases/download/v2.0.0/SHA256SUMS.txt) from the same release, verify the hash, extract the ZIP and copy its inner `blender-mcp-master` folder to your agent's skills directory. Full [Windows and agent setup instructions](docs/QUICKSTART.md).
With a current Skills CLI, pin the same release tag:
```bash
npx skills add God-601/blender-mcp-master@v2.0.0 --skill blender-mcp-master -g
```
**2. Set up Blender control separately**
Connect a compatible Blender-control MCP and its addon; discover the actual tool names and Blender version. Start in a scratch or backed-up scene. The skill supplies guidance, **not** a live Blender connection.
<details>
<summary><strong>Optional: read-only MCP resource server</strong></summary>
Start the optional read-only MCP resource server from the stable GitHub tag:
```bash
npx -y "github:God-601/blender-mcp-master#v2.0.0"
```
Configure Blender scene control separately.
</details>
<p align="center"><img src="assets/workflow.svg" width="100%" alt="Clarify, plan, build, inspect and correct workflow diagram"></p>
The skill adapts its design questions to the brief, plans
modeling by task, and checks evaluated geometry, scene preservation, UVs,
materials and game-asset budgets. The quality toolkit includes conservative
component-fit and containment diagnostics, PNG silhouette measurements,
PBR channel inspection, and evidence-backed specialist review reports.
**Verified in CI:** Blender bpy regression suites, a real Cycles texture-bake
fixture, and Blender-authored GLB import in Godot 4.4.1. **User-reported
Roblox Studio acceptance:** Sofa V3 LOD meshes and PBR maps were inspected
and the user approved the visible result. This does *not* certify universal
Roblox/Unity compatibility or artistic quality.
See the [v2.0.0 release notes](docs/release-notes-2.0.md),
[game export guidance](references/game-ready-export.md), and the
[v1.5–1.9 milestone status](docs/V1.5-V2.0-MILESTONES.md).
## Workflow
```text
USER BRIEF + REFERENCE
|
v
BLENDER MCP MASTER [Agent Skill]
Clarify -> Plan -> Blockout -> Refine -> Verify
| ^
v |
BLENDER-CONTROL MCP ------------------+
|
Blender scene
```
The agent must **inspect before it claims success**. Geometry checks, screenshots, and target-format checks answer different questions; missing evidence is **NOT VERIFIED**, not a pass.
| Focus | What changes |
| :--- | :--- |
| **Scene safety** | Explicit targets, owned collections, backup-first changes |
| **Modeling quality** | Proportion checks before unnecessary micro-detail |
| **Technical validity** | Evaluated topology, modifiers, UVs, materials, and budgets |
| **Visual validation** | Real viewport views before judging appearance |
| **Delivery** | `PASS / ISSUE / N/A / NOT VERIFIED` plus known limitations |
Supported workflows include hard-surface props, organic modeling, stylized and low-poly assets, architecture, environments, characters, UV/baking, materials, and game-ready exports. Available features depend on the actual Blender installation and connected MCP tools.
<p align="center"><img src="assets/architecture.svg" width="100%" alt="Skill and separate Blender-control MCP architecture"></p>
## Documentation
| Resource | Purpose |
| :--- | :--- |
| [Quickstart](docs/QUICKSTART.md) | Installation, Windows paths, checksums, and MCP setup |
| [SKILL.md](SKILL.md) | Main instruction entrypoint for agents |
| [Official Blender documentation](references/official-blender-documentation.md) | Curated modeling, modifiers, UV, Geometry Nodes, Python API, export references |
| [Evidence-first workflow](references/evidence-first-workflow.md) | Stage gates, independent review, defect diagnosis, and stop conditions |
| [Modeling standards](references/professional-modeling-standards.md) | Production requirements and quality evidence |
| [Production recipes](references/production-recipes.md) | Concrete modeling examples |
| [Skill comparisons](docs/ECOSYSTEM-COMPARISON.md) | Reference patterns, including Superpowers |
| [Roadmap v2.0](docs/ROADMAP-V2.md) | Production architecture, staged acceptance gates and remaining validation |
| [v1.5–v1.9 milestones](docs/V1.5-V2.0-MILESTONES.md) | Candidate capabilities and open acceptance gates |
| [Roblox Studio inspection](integrations/roblox/README.md) | Read-only MeshPart/PBR/LOD inspection procedure |
| [Godot GLB import](integrations/godot/README.md) | Executable import probe, scope and limitations |
| [Agent efficiency](references/token-efficient-agent-execution.md) | Tool-first, bounded reads and progressive context loading |
| [3D model optimization](references/model-performance-strategy.md) | Evaluated triangle, material, texture and Geometry Nodes guidance |
| [Paired token benchmark](docs/EFFICIENCY-BENCHMARK.md) | Reproducible with/without skill comparison protocol |
<details>
<summary><strong>Tests and contribution</strong></summary>
```bash
python -m unittest discover -s tests -v
```
Some tests require a compatible `bpy` runtime. Passing tests is not proof of artistic quality or live MCP and downstream export compatibility.
[Milestones v1.5–1.9](docs/V1.5-V2.0-MILESTONES.md) · [Roadmap v2.0 and pre-release audit](docs/ROADMAP-V2.md) · [Quality checklist](references/quality-checklist.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
</details>
---
<a id="portugues"></a>
# Português
**Uma skill para agentes de IA modelarem no Blender com método e evidências.** Ajuda a planejar, modelar, verificar topologia, UVs, materiais PBR e preparar assets para jogos. Ela orienta o agente; não instala nem substitui o Blender-control MCP.
- **Instale a v2.0.0 pelo** [ZIP da release](https://github.com/God-601/blender-mcp-master/releases/download/v2.0.0/blender-mcp-master-2.0.0.zip) ou com `npx skills add God-601/blender-mcp-master@v2.0.0 --skill blender-mcp-master -g`.
- **Servidor de recursos opcional** de somente leitura via `npx -y "github:God-601/blender-mcp-master#v2.0.0"`.
- **Configurar:** conectar separadamente um Blender-control MCP. Veja o [guia para Windows e agentes](docs/QUICKSTART.md).
- **Fluxo:** esclarecer → planejar → modelar → inspecionar → corrigir → relatar o que foi verificado.
- **Aprofundar:** [documentação oficial](references/official-blender-documentation.md) · [verificação e recuperação](references/evidence-first-workflow.md) · [padrões profissionais](references/professional-modeling-standards.md).
Inclui verificações técnicas e exemplos reais de baking e importação no Godot. Um sofá com três LODs e mapas PBR foi aprovado pelo usuário em uma campanha anterior no Roblox Studio.
A 2.0 reúne módulos especializados, executor por adaptador
do cliente, um escritor por vez, QA independente e recibos com SHA256.
Tarefas simples ficam com o coordenador. O adaptador deve fornecer as
ferramentas reais do Blender; a ponte de revisão Codex é somente leitura.
[Contrato e uso](references/specialist-orchestration.md) ·
[Evidências e pendências](docs/V2-EVIDENCE.md).
[Notas da v2.0.0](docs/release-notes-2.0.md) · [Roadmap 2.0](docs/ROADMAP-V2.md) · [Guia Roblox Studio](integrations/roblox/README.md)
<p align="center">
<a href="LICENSE">MIT License</a> ·
<a href="https://github.com/God-601/blender-mcp-master/issues">Feedback</a> ·
<a href="https://github.com/God-601/blender-mcp-master/releases">Releases</a>
</p>
TDQS
Scored across 8 tools
Each tool has a distinct role: skill instructions, resource listing, reference reading, outline, excerpt, script retrieval, setup explanation, and workflow planning. The three reference-reading tools (get_blender_reference, get_blender_reference_outline, get_blender_reference_excerpt) operate on the same documents at different granularities, which could cause some misselection, but the descriptions clearly delineate low-context vs. bounded-window vs. full-read use cases.
All tools follow a uniform snake_case verb_noun pattern scoped by the domain (get_blender_*, list_blender_*, plan_blender_workflow). No mixed conventions or abbreviation drift, making intent predictable from the name alone.
Eight tools is well-scoped for a read-only skill/resource server with no redundancy. Every tool maps to a distinct access pattern (metadata, full read, outline, excerpt, script, setup, planning) and none feels padded.
The read-only resource surface is largely complete: discovery, granular reading, scripts, setup context, and planning are all covered. The main gap is a search/lookup tool to find which reference covers a topic without first listing files; otherwise no dead ends for the stated purpose.