blender-mcp

MCP-сервер для создания .blend-файлов Blender. Работает с Blender двумя способами:

• Headless — каждый вызов запускает новый процесс blender --background. Детерминированно, всегда доступен и подходит для генерации файлов.

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

Оба маршрута используют один и тот же код обработчиков, поэтому скрипт ведёт себя одинаково в любом режиме. Локальный веб-интерфейс позволяет загружать референсные изображения и запускать задачи генерации с помощью тех же инструментов.

Требования

Related MCP server: Blender MCP

Настройка

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

Если пропустить .env, сервер ищет Blender в PATH и стандартных папках Program Files/Blender Foundation/Blender <version> на всех дисках, отдавая предпочтение самой новой найденной версии.

Включение live-моста

Аддон установлен, но неактивен, пока вы его не запустите:

1. Откройте Blender.

2. Нажмите N в 3D-вьюпорте, чтобы показать боковую панель.

3. Откройте вкладку MCP и нажмите Start MCP Bridge.

Отметьте Start listening on launch в настройках аддона, чтобы пропустить этот шаг в будущем.

Подключение MCP-клиента

.cursor/mcp.json уже регистрирует сервер для этого проекта. Чтобы сделать его доступным везде, скопируйте этот блок в ~/.cursor/mcp.json:

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

Рабочий процесс для качества

Качество генерации достигается через просмотр, а не через единый скрипт:

1. list_references / view_reference — сначала откройте направляющие изображения

2. create_blend из studio или product

3. Стройте небольшими шагами run_script; apply_material для металла/пластика/резины/стекла/дерева

4. preview_views — многовидовые превью EEVEE; сравните с референсами через view_image

5. Исправляйте, снова просматривайте

6. Финальный render / render_and_view (только CYCLES для финала; EEVEE во время итераций)

Локальный веб-интерфейс

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

Загружайте референсные изображения, вводите промпт и просматривайте задачи в output/jobs/.

• С BLENDER_MCP_LLM_API_KEY в .env — сайт запускает ограниченный мультимодальный агент, который вызывает те же инструменты Blender (совместимый с OpenAI или Anthropic через BLENDER_MCP_LLM_PROVIDER).

• Без ключа — загрузка и страницы задач всё равно работают; откройте задачу в Cursor и попросите MCP-агента собрать из output/jobs/<id>/refs.

Инструменты

Написание скриптов

run_script и аргумент script в create_blend выполняются в пространстве имён, где уже доступны bpy, mathutils, math, D (bpy.data) и C (bpy.context). Отправляйте данные обратно, присваивая значение result или вызывая emit(value).

Шаблоны

Структура

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/

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

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

Примечания и ограничения

• run_script выполняет произвольный Python-код внутри Blender. Держите мост на loopback.

• Длительный рендер блокирует живой интерфейс до завершения.

• viewport_screenshot работает только в live-режиме.

• Cycles использует CPU, если не включить GPU-устройство в настройках Blender.

• Веб-агенту нужна мультимодальная модель, поддерживающая вызовы инструментов и изображения.

Лицензия

MIT