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.2.0 (alpha). La API del puente usa el contrato versionado 1.0.

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
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.2.0.zip.

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