blender-control-mcp

blender-control-mcp es un servidor MCP STDIO independiente que controla Blender de forma segura en modo background en Windows local. No incluye LLM, interpretación de lenguaje natural ni ejecución arbitraria de Python/shell. Solo se pueden usar los 7 herramientas estructuradas que expone el servidor, y las entradas se validan tanto en el host como dentro de Blender.

Requisitos

• Windows

• Python 3.12 o superior

• Se recomienda Blender 5.2 LTS

• Ruta predeterminada de Blender: C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe

Related MCP server: blend-ai

Instalación

Ejecute en PowerShell desde la raíz del proyecto.

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Si Blender está en otra ubicación, configure la variable de entorno.

$env:BLENDER_EXECUTABLE = "D:\Apps\Blender\blender.exe"

Variables de entorno opcionales:

• BLENDER_EXECUTABLE: ruta de blender.exe

• BLENDER_TIMEOUT_SECONDS: timeout de una operación, de 1 a 3600 segundos, por defecto 180 segundos

• BLENDER_CONTROL_WORKDIR: raíz de almacenamiento de registros/planes de las operaciones de inspección de solo lectura. El valor predeterminado es %TEMP%\blender-control-mcp

Ejecución del servidor

.\.venv\Scripts\blender-control-mcp.exe

O también puede ejecutarlo de la siguiente manera.

.\.venv\Scripts\python.exe -m blender_control_mcp.server

Al ser un servidor STDIO, en una ejecución normal no imprime un prompt interactivo ni registros comunes en stdout. El cliente MCP inicia el proceso e intercambia JSON-RPC.

Conexión con Codex

Codex admite servidores MCP STDIO locales y se puede configurar en ~/.codex/config.toml del usuario o en .codex/config.toml de un proyecto de confianza. La ruta siguiente es un ejemplo que usa la ubicación predeterminada de este repositorio.

[mcp_servers.blender_control]
command = "C:/Users/park/Desktop/dev_tool/blender-control-mcp/.venv/Scripts/python.exe"
args = ["-m", "blender_control_mcp.server"]
cwd = "C:/Users/park/Desktop/dev_tool/blender-control-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 300
default_tools_approval_mode = "writes"

[mcp_servers.blender_control.env]
BLENDER_EXECUTABLE = "C:/Users/park/Applications/blender-5.2.0-windows-x64/blender.exe"
BLENDER_TIMEOUT_SECONDS = "180"

Después de la configuración, reinicie Codex y verifique el estado de la conexión con /mcp o codex mcp list. En la interfaz de usuario también puede seleccionar Settings → MCP servers → Add server → STDIO e ingresar el mismo command/args. Consulte la documentación de MCP de Codex de OpenAI para conocer los elementos de configuración más recientes.

Un ejemplo de adición mediante CLI es el siguiente.

codex mcp add blender_control --env BLENDER_EXECUTABLE=C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe -- C:\Users\park\Desktop\dev_tool\blender-control-mcp\.venv\Scripts\python.exe -m blender_control_mcp.server

Conexión con otros clientes MCP

Este es un ejemplo típico para clientes cuyo formato de configuración de servidor STDIO es JSON. Verifique la ubicación real del archivo de configuración y los nombres de las claves en la documentación del cliente.

{
  "mcpServers": {
    "blender-control": {
      "command": "C:\\Users\\park\\Desktop\\dev_tool\\blender-control-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "blender_control_mcp.server"],
      "env": {
        "BLENDER_EXECUTABLE": "C:\\Users\\park\\Applications\\blender-5.2.0-windows-x64\\blender.exe"
      }
    }
  }
}

Herramientas

Todas las entradas de ruta son cadenas. Los activos de entrada solo admiten .glb, .blend y .fbx. target debe ser all o un nombre que coincida exactamente, incluido el uso de mayúsculas y minúsculas. Si no se encuentra o es ambiguo, el servidor no elige arbitrariamente y devuelve un error target_not_found/ambiguous_target junto con la lista de candidatos.

scene.inspect

Entrada:

{"input_path":"C:\\assets\\chair.glb"}

data.objects devuelve nombre, tipo, ranuras de material, número de vértices/polígonos de la malla, dimensions, location y la lista de Modifiers.

{
  "success": true,
  "data": {
    "object_count": 1,
    "objects": [{
      "name": "Chair",
      "type": "MESH",
      "material_slots": ["Wood"],
      "vertex_count": 1200,
      "polygon_count": 800,
      "dimensions": [1.0, 1.1, 1.8],
      "location": [0.0, 0.0, 0.0],
      "modifiers": []
    }]
  }
}

material.list

Entrada:

{"input_path":"C:\\assets\\chair.blend"}

Ejemplo de respuesta:

{
  "success": true,
  "data": {
    "material_count": 1,
    "materials": [{
      "name": "Wood",
      "base_color": [0.4, 0.2, 0.1, 1.0],
      "roughness": 0.55,
      "metallic": 0.0,
      "alpha": 1.0,
      "base_color_texture_linked": true
    }]
  }
}

asset.apply_material

base_color es RGB o RGBA en el rango 01, y roughness, metallic y alpha también están en el rango 01. Se requiere al menos un valor de cambio.

{
  "input_path":"C:\\assets\\chair.glb",
  "output_directory":"C:\\assets\\outputs",
  "target":"Wood",
  "base_color":[0.1,0.3,0.8,0.75],
  "roughness":0.25,
  "alpha":0.75
}

El objetivo es un nombre de material exacto o un nombre de objeto que tenga un solo material. Genera los archivos GLB, BLEND y FBX modificados. Si un objeto tiene varios materiales, devuelve los candidatos de material y exige una selección explícita.

asset.transform

Cada vector consta de 3 números. scale está entre 0.001 y 1000 por eje, y se requiere al menos un valor de cambio.

{
  "input_path":"C:\\assets\\chair.glb",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "location":[0,0,1],
  "rotation_degrees":[0,0,90],
  "scale":[1.2,1.2,1.2]
}

Genera los archivos GLB, BLEND y FBX modificados.

asset.add_modifier

Ejemplo de entrada de Bevel:

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"bevel",
  "width":0.03,
  "segments":3
}

Ejemplo de entrada de Decimate:

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"decimate",
  "ratio":0.5
}

Bevel solo admite width > 0~~1000 y segments de 1 a 16 (por defecto 0.1/3). Decimate solo admite ratio de 0.01 a 1 (por defecto 0.5). Se rechazan otros Modifiers o parámetros mezclados entre sí. Genera los tres formatos modificados.

asset.set_smooth_shading

{
  "input_path":"C:\\assets\\chair.fbx",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair"
}

Aplica smooth shading a los polígonos de la malla objetivo y genera los archivos GLB, BLEND y FBX modificados.

asset.export

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\exports",
  "formats":["glb","blend","fbx"]
}

formats debe contener uno o más de glb, blend y fbx sin duplicados, y solo se generan los formatos solicitados.

Respuestas comunes y artefactos

Todas las llamadas devuelven una respuesta estructurada. Las herramientas de modificación/exportación crean los artefactos en <output_directory>/<operation_id>/, y las herramientas de lectura dejan registros bajo la raíz de trabajo temporal.

{
  "success": true,
  "operation_id": "9bc12a7f57f24f8ba9d9af2f78de3041",
  "operation": "asset.export",
  "artifacts": [
    "C:\\assets\\exports\\9bc12a7f57f24f8ba9d9af2f78de3041\\chair.glb"
  ],
  "summary": "asset.export completed successfully",
  "data": {"formats":["glb"],"artifact_count":1},
  "operation_path": "...\\operation.json",
  "log_path": "...\\blender.log",
  "log_excerpt": "Blender 5.2.0 ...",
  "command": ["...\\blender.exe","--background","..."],
  "exit_code": 0,
  "errors": []
}

Incluso en caso de fallo, cuando es posible se dejan operation.json y blender.log, y se devuelven el código de error y los candidatos como se muestra a continuación.

{
  "success": false,
  "summary": "object target 'Seat' was not found",
  "artifacts": [],
  "errors": [{
    "code": "target_not_found",
    "message": "object target 'Seat' was not found",
    "candidates": ["Chair", "Table"]
  }]
}

Pruebas

Pruebas completas:

.\.venv\Scripts\python.exe -m pytest -q

En un entorno sin Blender, solo la prueba de integración real con Blender se omite automáticamente y las pruebas unitarias pasan.

# 빠른 단위 테스트만
.\.venv\Scripts\python.exe -m pytest -m "not integration" -q

# 실제 Blender 통합 테스트만
.\.venv\Scripts\python.exe -m pytest -m integration -q

La prueba de integración crea un GLB pequeño y luego verifica en Blender real la inspección de la escena, el cambio de color/rugosidad/transparencia del material, el cambio de escala, la adición de Bevel y la generación de GLB/BLEND/FBX.

Diseño de seguridad

• No existe ninguna herramienta que reciba Python arbitrario de Blender, cadenas de Python, planes en lenguaje natural o comandos de shell.

• El puente es un único blender_mcp_bridge.py fijo que vuelve a validar el tipo de operación, los campos y los valores JSON mediante una allow-list.

• El puente no contiene eval, exec, subprocess ni ejecución de comandos externos.

• Blender se ejecuta con --background --factory-startup --disable-autoexec.

• Se usa subprocess.run(..., shell=False) con una matriz de argumentos y se aplica timeout.

• Los archivos de entrada se validan en cuanto a existencia y extensión antes de ejecutar Blender.

• La salida se escribe únicamente en subcarpetas con un ID de operación aleatorio y no sobrescribe artefactos existentes ni el original.

• El puente vuelve a verificar que el plan, el resultado y los artefactos estén todos dentro del límite de la misma carpeta de trabajo de la operación.

Limitaciones del MVP

• No se admite la modificación de píxeles de texturas de imagen, Texture Paint ni el horneado (bake).

• En materiales donde el socket Base Color tiene una textura/nodo conectado, cambiar el valor predeterminado puede no alterar la apariencia final. En ese caso, se deja una advertencia en blender.log.

• El cambio de material solo admite materiales que tengan Principled BSDF.

• Los Modifiers solo agregan Bevel y Decimate, y no se aplican (apply). La forma en que el exporter del formato de exportación procesa el resultado evaluado sigue el comportamiento específico de cada formato de Blender.

• Los daños en el propio archivo de Blender, los errores del importer/exporter de Blender y las diferencias de funcionalidad entre formatos se reportan mediante errores estructurados y registros, pero no se reparan automáticamente.

• Cada llamada a una herramienta inicia un proceso de Blender independiente, por lo que en activos grandes el costo de inicio y conversión es alto.