Skip to main content
Glama
blender-MCP
by Berrio

Berrio Blender MCP

Servidor MCP y complemento de Blender para preparar personajes de videojuegos de forma segura, repetible y verificable.

El proyecto se concentra en operaciones de alto nivel. No expone una herramienta para ejecutar Python arbitrario dentro de Blender.

Estado

Versión 0.3.0 (alpha). La API del puente usa el contrato versionado 1.0.

Related MCP server: blendermcp

Arquitectura

Cliente MCP (Codex, inspector, IDE)
                │ stdio / Streamable HTTP local
                ▼
     Servidor Python FastMCP
       ├─ política de rutas
       ├─ dry-run por defecto
       └─ herramientas estructuradas
                │ JSONL + token, 127.0.0.1:9876
                ▼
       Complemento de Blender
       ├─ cola hacia el hilo principal
       ├─ operaciones permitidas
       └─ checkpoints de archivos .blend

Herramientas MCP

Herramienta

Función

blender_status

Comprueba conexión, versiones y capacidades

blender_scene_summary

Resume escena, armaduras, mallas y acciones

blender_list_objects

Lista objetos sin modificar la escena

blender_validate_character

Valida rig, clips, límites, materiales y dimensiones

blender_create_humanoid_character

Genera un Forjador del Éter original, riggeado y animado, compacto o semirrealista

blender_import_asset

Importa FBX, GLB, GLTF u OBJ

blender_normalize_character

Normaliza altura, centro y contacto con el suelo

blender_rename_actions

Convierte nombres de clips a un contrato estable

blender_export_character_glb

Exporta armadura, mallas y animaciones a GLB

Las operaciones que cambian archivos o escenas usan dry_run=true de manera predeterminada.

Requisitos

  • Python 3.11 o posterior.

  • uv para un entorno reproducible.

  • Blender 4.2 o posterior para el complemento.

Preparar el servidor

uv sync --extra dev
uv run pytest
uv run python scripts/build_addon.py

El último comando genera dist/blender_mcp_bridge-0.3.0.zip.

Arquetipos originales

Arquetipo

Uso recomendado

Complejidad aproximada

ether-forger

Fallback compacto y prototipos

18 huesos, 12.396 triángulos, 8 materiales

ether-forger-v2

Héroe semirrealista para el juego

39 huesos, 40.522 triángulos evaluados, 12 materiales

V2 añade proporciones humanas mejoradas, dedos, rasgos faciales, cabello por mechones, ropa dividida, armadura laminada, huesos de torsión y abrigo, y microdetalle procedural en los materiales. Sigue siendo un activo semirrealista optimizado para juego; no sustituye un flujo de escultura y texturizado humano fotorrealista.

Para instalar una copia portátil verificada de Blender 4.5 LTS dentro de .tools:

powershell -ExecutionPolicy Bypass -File scripts\install_blender_portable.ps1

El script descarga desde download.blender.org, compara la suma SHA-256 oficial y solo después extrae el programa. .tools está excluido de Git.

Instalar el complemento

  1. En Blender, abre Edit → Preferences → Add-ons.

  2. Selecciona Install from Disk e instala el ZIP generado.

  3. Activa Berrio Blender MCP Bridge.

  4. Opcionalmente configura un token en las preferencias.

  5. Abre 3D View → Sidebar → Blender MCP y pulsa Start MCP Bridge.

El puente solo acepta conexiones de loopback. Si se configura un token, el servidor MCP debe recibir el mismo valor en BLENDER_MCP_TOKEN.

Ejecutar mediante stdio

uv run blender-mcp

Configuración MCP genérica:

{
  "mcpServers": {
    "blender-character-pipeline": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ruta\\a\\blender-MCP",
        "run",
        "blender-mcp"
      ],
      "env": {
        "BLENDER_MCP_WORKSPACE_ROOTS": "C:\\ruta\\a\\Repos",
        "BLENDER_MCP_TOKEN": "el-mismo-token-de-blender"
      }
    }
  }
}

También puede ejecutarse mediante Streamable HTTP restringido al equipo local:

uv run blender-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Skill de personajes para Codex

La skill versionada en skills/blender-character-pipeline enseña a Codex a diagnosticar por capas, ejecutar cambios primero como simulación y distinguir problemas del activo Blender de fallos de animación, navegación o control dentro del motor.

Instálala en el perfil actual de Codex:

powershell -ExecutionPolicy Bypass -File scripts\install_codex_skill.ps1

Registra después este servidor MCP con el mismo nombre declarado por la skill:

codex mcp add blender-character-pipeline `
  --env BLENDER_MCP_WORKSPACE_ROOTS=C:\ruta\a\Repos `
  -- uv --directory C:\ruta\a\blender-MCP run blender-mcp

Reinicia Codex después de instalarla o actualizarla. Invócala explícitamente con $blender-character-pipeline, aunque también puede activarse al trabajar con personajes .blend, FBX, GLB, GLTF u OBJ.

Seguridad

  • Solo se permite 127.0.0.1, localhost o ::1.

  • No existe una operación de código arbitrario.

  • Las rutas se restringen con BLENDER_MCP_WORKSPACE_ROOTS.

  • Las mutaciones comienzan como simulaciones.

  • Importar, normalizar y renombrar pueden crear checkpoints del .blend guardado.

  • Los mensajes tienen límites de tamaño y tiempo.

Un proceso local que comparta la cuenta del sistema sigue teniendo acceso a los mismos archivos. Usa un token cuando convivan procesos que no sean de confianza.

Flujo recomendado para personajes

  1. Consultar estado y resumen de escena.

  2. Simular la generación ether-forger, ether-forger-v2 o la importación y luego ejecutarla explícitamente.

  3. Validar armadura, mallas, presupuesto y clips.

  4. Simular y ejecutar la normalización.

  5. Renombrar clips a Idle, Walk, Run, Attack, Dodge, Hit y Death.

  6. Validar otra vez.

  7. Simular y ejecutar la exportación GLB.

  8. Conservar el archivo fuente y la licencia del activo.

Desarrollo

uv run ruff check .
uv run pytest --cov=blender_mcp --cov-report=term-missing
uv run python scripts/smoke_mcp.py

La prueba de humo inicia el servidor por stdio, negocia una sesión MCP real, enumera las herramientas y comprueba blender_status. Las pruebas del puente usan un Blender simulado; las operaciones bpy deben comprobarse adicionalmente dentro de Blender.

Con la copia portátil, la integración real se comprueba en modo de fábrica y sin interfaz:

& '.\.tools\blender-4.5.10-windows-x64\blender.exe' `
  --background --factory-startup --python scripts\blender_integration_test.py

El contrato JSONL entre el servidor y el complemento está documentado en docs/BRIDGE_PROTOCOL.md.

Licencia

MIT. Las licencias de modelos, texturas y animaciones procesados por este servidor permanecen bajo sus términos originales.

Available Tools

9 tools
blender_create_humanoid_characterB

Plan or generate an original rigged humanoid with seven canonical game actions.

Inputs: name, dry_run, height_m, archetype, +2 more.

blender_export_character_glbB

Plan or export one armature and its bound meshes as an optimized game-ready GLB.

Inputs: filepath (required), dry_run, armature_name, include_animations.

blender_import_assetB

Plan or import a supported character asset. Mutation requires dry_run=false.

Inputs: filepath (required), dry_run, create_checkpoint.

blender_list_objectsA

List Blender scene objects without modifying the scene.

Inputs: limit, object_type.

blender_normalize_characterC

Plan or normalize a character's height, horizontal center, and ground placement.

Inputs: dry_run, center_xy, armature_name, place_on_ground, +2 more.

blender_rename_actionsB

Plan or rename Blender actions to stable game-facing clip names.

Inputs: mapping (required), dry_run, create_checkpoint.

blender_scene_summaryA

Summarize the open Blender file, object counts, armatures, meshes, actions, and save state.

Inputs: no named parameters.

blender_statusA

Check whether the local Blender add-on bridge is running and report its capabilities.

Inputs: no named parameters.

blender_validate_characterA

Validate a humanoid for game export: rig, meshes, actions, bounds, triangles, and materials.

Inputs: armature_name, material_budget, triangle_budget, required_actions.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct stage or aspect of the character pipeline: status, scene info, object listing, import, creation, validation, normalization, action renaming, and export. There is no meaningful overlap between tool purposes, and descriptions clearly distinguish read-only actions from mutating ones.

    Naming Consistency4/5

    All tools share the 'blender_' prefix and use snake_case, with most following a verb_noun pattern (import_asset, list_objects, validate_character). The exceptions are blender_status and blender_scene_summary, which use noun-only or noun_noun naming, creating a minor inconsistency.

    Tool Count5/5

    With 9 tools, the set is well-scoped for the stated domain of Blender character preparation and export. Each tool covers a necessary step without redundant or excessive additions, fitting comfortably within the ideal 3-15 range.

    Completeness4/5

    The toolset covers the core lifecycle for character assets: import, create, validate, normalize, rename actions, and export. Minor gaps exist (e.g., no tool for direct editing of meshes or armatures), but the provided suite is sufficient for a complete character pipeline from import to game-ready export.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables remote control of Blender through MCP, allowing code execution, scene manipulation, rendering, and file transfer in a containerized environment.
      1
      -
    • A
      license
      C
      quality
      B
      maintenance
      Enables secure, local automation of Blender through typed MCP tools for scene, modeling, material, animation, rendering, and file workflows via an authenticated loopback bridge.
      173
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible clients to control Blender for modeling, materials, animation, physics, rendering, scene inspection, documentation search, and asset/generation service integration. It exposes a stdio endpoint with many Blender operations for creating and editing 3D content.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable AI clients to control a local Blender workstation through a secure HTTP gateway for 3D scene inspection, modeling, rigging, animation, materials, rendering, import/export, and controlled Python automation. Supports permission profiles and authentication modes to keep Blender execution local while allowing AI-assisted production workflows.
      1
      MIT