blender-mcp

Un servidor MCP que construye archivos .blend de Blender. Se conecta a Blender de dos formas:

• Headless — cada llamada inicia un proceso blender --background nuevo. Determinista, siempre disponible, y la opción adecuada para generar archivos.

• Live — un pequeño addon de Blender abre un puerto local para que el servidor pueda controlar la ventana de Blender que ya tienes abierta, y puedes verlo en acción.

Ambas rutas ejecutan el mismo código de manejador, por lo que un script se comporta de forma idéntica en cualquier caso. Una interfaz web local te permite subir imágenes de referencia y ejecutar trabajos de generación con las mismas herramientas.

Requisitos

Related MCP server: Blender MCP

Configuración

uv sync                                        # create .venv and install
cp .env.example .env                           # then set BLENDER_MCP_EXECUTABLE
uv run python scripts/build_addon.py --install # build + install the Blender addon

Si omites .env, el servidor busca en tu PATH y en las carpetas estándar Program Files/Blender Foundation/Blender <version> de cada unidad, prefiriendo la versión más nueva que encuentre.

Activando el puente en vivo

El addon está instalado pero inactivo hasta que lo inicies:

1. Abre Blender.

2. Presiona N en el viewport 3D para mostrar la barra lateral.

3. Abre la pestaña MCP y haz clic en Start MCP Bridge.

Marca Start listening on launch en las preferencias del addon para omitir este paso cada vez.

Conectando un cliente MCP

.cursor/mcp.json ya registra el servidor para este proyecto. Para hacerlo disponible en todas partes, copia ese bloque en ~/.cursor/mcp.json:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\josef\\Projects\\blender-mcp", "blender-mcp"]
    }
  }
}

Flujo de trabajo de calidad

La calidad de la generación viene de observar, no de un solo volcado de script:

1. list_references / view_reference — abre primero las imágenes guía

2. create_blend desde studio o product

3. Construye en pequeños pasos con run_script; apply_material para metal/plástico/goma/vidrio/madera

4. preview_views — previsualizaciones EEVEE multiángulo; compara con las referencias usando view_image

5. Corrige, previsualiza de nuevo

6. render / render_and_view final (CYCLES solo para finales; EEVEE durante la iteración)

Interfaz web local

uv run blender-mcp-web
# open http://127.0.0.1:8765

Sube imágenes de referencia, introduce un prompt y explora los trabajos en output/jobs/.

• Con BLENDER_MCP_LLM_API_KEY en .env — el sitio ejecuta un agente multimodal acotado que llama a las mismas herramientas de Blender (compatible con OpenAI o Anthropic mediante BLENDER_MCP_LLM_PROVIDER).

• Sin clave — las subidas y las páginas de trabajo siguen funcionando; abre el trabajo en Cursor y pídele al agente MCP que construya a partir de output/jobs/<id>/refs.

Herramientas

Escribiendo scripts

run_script y el argumento script de create_blend se ejecutan en un espacio de nombres donde bpy, mathutils, math, D (bpy.data) y C (bpy.context) ya están vinculados. Envía datos de vuelta asignando a result o llamando a emit(value).

Plantillas

Estructura

addon/blender_mcp_addon/   Blender extension + shared handlers (incl. preview_views)
src/blender_mcp/
  server.py                MCP tools
  refs.py                  reference image library
  materials.py             procedural material presets
  templates.py             starter scenes
  agent/                   bounded multimodal generation loop
  web/                     FastAPI UI (templates + static)
  headless.py / bridge.py  Blender process / live socket
scripts/                   build, install, verification
output/                    .blend files, renders, refs/, jobs/

Pruebas

uv run pytest -m "not blender"   # fast
uv run pytest                    # includes real Blender runs
uv run python scripts/check_server.py
uv run python scripts/verify_live_bridge.py

Notas y límites

• run_script ejecuta código Python arbitrario dentro de Blender. Mantén el puente en la interfaz de loopback.

• Los renders largos bloquean la interfaz en vivo hasta que terminan.

• viewport_screenshot solo funciona en vivo.

• Cycles usa CPU a menos que habilites un dispositivo GPU en las preferencias de Blender.

• El agente web necesita un modelo multimodal que admita llamadas a herramientas e imágenes.

Licencia

MIT