blender-control-mcp

blender-control-mcp — это автономный STDIO MCP-сервер для безопасного управления Blender в фоновом режиме на локальной Windows. Он не включает LLM, интерпретацию естественного языка или произвольное выполнение Python/команд оболочки. Доступны только 7 структурированных инструментов, предоставляемых сервером; входные данные проверяются как на хосте, так и внутри Blender.

Требования к окружению

• Windows

• Python 3.12 или новее

• Рекомендуется Blender 5.2 LTS

• Путь к Blender по умолчанию: C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe

Related MCP server: blend-ai

Установка

Выполните в PowerShell из корня проекта.

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

Если Blender находится в другом месте, задайте переменную окружения.

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

Необязательные переменные окружения:

• BLENDER_EXECUTABLE: путь к blender.exe

• BLENDER_TIMEOUT_SECONDS: таймаут одной операции, 1~3600 секунд, по умолчанию 180 секунд

• BLENDER_CONTROL_WORKDIR: корневой каталог для хранения журналов/планов операций проверки только для чтения. По умолчанию — %TEMP%\blender-control-mcp

Запуск сервера

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

Или можно запустить следующим образом:

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

Поскольку это STDIO-сервер, при нормальной работе он не выводит интерактивные подсказки или обычные журналы в stdout. MCP-клиент запускает процесс и обменивается JSON-RPC.

Подключение Codex

Codex поддерживает локальные STDIO MCP-серверы; его можно настроить в ~/.codex/config.toml пользователя или в .codex/config.toml доверенного проекта. Ниже приведён пример с путями по умолчанию из этого репозитория.

[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"

После настройки перезапустите Codex и проверьте состояние подключения через /mcp или codex mcp list. В UI можно выбрать Settings → MCP servers → Add server → STDIO и ввести те же command/args. Актуальные параметры настройки см. в документации Codex MCP от OpenAI.

Пример добавления через CLI:

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

Подключение других MCP-клиентов

Типичный пример для клиентов, у которых формат настройки STDIO-сервера — JSON. Фактическое расположение файла конфигурации и имена ключей уточняйте в документации клиента.

{
  "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"
      }
    }
  }
}

Инструменты

Все пути передаются строками. Входные ассеты допускаются только .glb, .blend, .fbx. target должен быть all или именем, точно совпадающим с учётом регистра. Если объект не найден или имя неоднозначно, сервер не выбирает произвольно, а возвращает ошибку target_not_found/ambiguous_target и список кандидатов.

scene.inspect

Входные данные:

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

В data.objects возвращаются имя, тип, слоты материалов, число вершин/полигонов меша, dimensions, location и список модификаторов.

{
  "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

Входные данные:

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

Пример возвращаемого значения:

{
  "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 — это RGB или RGBA в диапазоне 01; roughness, metallic и alpha также находятся в диапазоне 01. Требуется хотя бы одно изменяемое значение.

{
  "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
}

Целью является точное имя материала или имя объекта, у которого только один материал. Создаются все изменённые форматы GLB, BLEND, FBX. Если у объекта несколько материалов, возвращаются кандидаты материалов и требуется явный выбор.

asset.transform

Каждый вектор состоит из 3 чисел. scale — от 0.001~1000 по каждой оси; требуется хотя бы одно изменяемое значение.

{
  "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]
}

Создаются все изменённые форматы GLB, BLEND, FBX.

asset.add_modifier

Пример входных данных Bevel:

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

Пример входных данных Decimate:

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

Bevel допускает только width > 01000 и segments 116 (по умолчанию 0.1/3). Decimate допускает только ratio 0.01~1 (по умолчанию 0.5). Другие модификаторы или смешанные параметры отклоняются. Создаются все три изменённых формата.

asset.set_smooth_shading

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

Устанавливает smooth shading для полигонов целевого меша и создаёт все изменённые форматы GLB, BLEND, FBX.

asset.export

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

formats должен содержать один или несколько форматов из glb, blend, fbx без дубликатов; создаются только запрошенные форматы.

Общие ответы и артефакты

Каждый вызов возвращает структурированный ответ. Инструменты изменения/экспорта создают артефакты в <output_directory>/<operation_id>/, а инструменты чтения оставляют журналы во временном корневом каталоге операций.

{
  "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": []
}

При сбое, если возможно, сохраняются operation.json и blender.log, а также возвращаются код ошибки и кандидаты, как показано ниже.

{
  "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"]
  }]
}

Тестирование

Все тесты:

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

В среде без Blender автоматически пропускается только один интеграционный тест с реальным Blender, а модульные тесты проходят.

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

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

Интеграционный тест создаёт небольшой GLB, а затем проверяет в реальном Blender инспекцию сцены, изменение цвета/шероховатости/прозрачности материала, изменение scale, добавление Bevel и создание GLB/BLEND/FBX.

Архитектура безопасности

• Нет инструментов, принимающих произвольный Python для Blender, строки Python, планы на естественном языке или команды оболочки.

• Мост — это единственный фиксированный файл blender_mcp_bridge.py, который повторно проверяет тип/поля/значения JSON-операции по allow-list.

• В мосте нет eval, exec, subprocess или выполнения внешних команд.

• Blender запускается с флагами --background --factory-startup --disable-autoexec.

• Используется subprocess.run(..., shell=False) с массивом аргументов и применяется таймаут.

• Входные файлы проверяются на существование и расширение до запуска Blender.

• Вывод записывается только в подпапку со случайным operation ID; существующие артефакты и исходники не перезаписываются.

• Мост повторно проверяет, что план, результат и артефакты находятся в границах одной папки операции.

Ограничения MVP

• Изменение пикселей текстур изображений, Texture Paint и запекание не поддерживаются.

• Для материалов, у которых к сокету Base Color подключены текстуры/узлы, изменение значения по умолчанию может не изменить конечный вид. В этом случае в blender.log записывается предупреждение.

• Изменение материалов поддерживается только для материалов с Principled BSDF.

• Из модификаторов добавляются только Bevel и Decimate, без применения (apply). То, как экспортёр обрабатывает вычисленный результат, зависит от поведения конкретного формата Blender.

• Повреждение самого файла Blender, ошибки импортёра/экспортёра Blender и различия функций между форматами сообщаются структурированными ошибками и журналами, но не восстанавливаются автоматически.

• Каждый вызов инструмента запускает отдельный процесс Blender, поэтому для больших ассетов затраты на запуск и преобразование значительны.