livadies / blender-ai-bridge

Blender + AI: как подключить любую нейросеть к Blender

Назначение этого репозитория: дать нейросети с абсолютно нулевым контекстом всё, что нужно, чтобы за несколько минут начать управлять живым Blender кодом. Никаких предварительных знаний о Blender, Python или MCP не требуется — только этот документ.

Кому адресовано: агенту (Claude, GPT, Gemini, локальной модели — любой), которого подключили к Blender и который не знает, с чего начать. Читай по порядку.

Статус: проверено на живом Blender 5.2.1 LTS, аддон blend-ai v1.3.0, Windows 11.

---

TL;DR — минимум, чтобы начать (3 шага)

1. Blender: N в 3D-вьюпорте → вкладка blend-ai → Start Server (порт 9876 ).
2. Скачать: git clone https://github.com/HoldMyBeer-gg/blend-ai + uv pip install -e .
3. Проверить связь: отправить {"command": "get_scene_info"} на 127.0.0.1:9876 .

Если ответ пришёл — можно работать. Всё остальное ниже.

---

1. Что это вообще такое (архитектура за 30 секунд)

Тут два раздельных куска , и путать их — самая частая ошибка:

┌──────────────┐   MCP / stdio    ┌─────────────────┐   TCP socket     ┌──────────────┐
│  Нейросеть   │ ───────────────► │  MCP-сервер     │ ───────────────► │  Аддон       │
│  (клиент)    │ ◄─────────────── │  blend-ai       │ ◄─────────────── │  внутри      │
└──────────────┘                  │  (Python, у вас)│  127.0.0.1:9876  │  Blender     │
                                  └─────────────────┘                  └──────────────┘
                                        "клиент"                       "сервер" (внутри Blender)

Ключевое, что нужно понять: Blender — это сервер . Он принимает входящие соединения. Нейросеть — клиент. Поэтому порт должен быть открыт в Blender до того , как агент попробует подключиться. Если Blender не запущен или сервер не нажат — подключения не будет, и выглядит это как «агент не работает», хотя проблема на стороне Blender.

Важно про терминологию. В этом репозитории слово «сервер» перегружено: аддон внутри Blender называется сервером (он слушает порт), а MCP-процесс в докe называется сервером MCP (он слушает stdio). Когда говорят «включи сервер» — обычно имеют в виду кнопку в Blender . Держи это в голове при чтении чужих инструкций.

---

2. Порт — самое главное число

Порт можно менять. Поле Port в N-панели, сохраняется в сцене как scene.blendai_port ( IntProperty , default 9876 , min 1024 , max 65535 ).

⚠️ Если поменял порт в Blender — поменяй его и на стороне клиента. Иначе получишь Connection refused , который выглядит как «Blender выключен».

Как проверить порт вручную

# Windows
netstat -ano | findstr :9876

# Linux / macOS
ss -ltnp | grep 9876    # или: lsof -i :9876

Если порт слушается — Blender готов. Если пусто — сервер в Blender не запущен.

Формат сообщения (для ручной отладки)

Запрос:

import json, socket, struct

sock = socket.create_connection(("127.0.0.1", 9876), timeout=30)
payload = json.dumps({"command": "get_scene_info", "params": {}}).encode("utf-8")
sock.sendall(struct.pack(">I", len(payload)) + payload)

length = struct.unpack(">I", sock.recv(4, socket.MSG_WAITALL))[0]
response = json.loads(sock.recv(length, socket.MSG_WAITALL).decode("utf-8"))
print(response)
sock.close()

Ответ всегда такой формы:

{
  "status": "ok",
  "result": { }
}

status бывает: "ok" | "error" | "busy" .

⚠️ "busy" — не ошибка. Пока Blender рендерит, главный поток занят, и сервер отвечает "busy" вместо выполнения. Правильное поведение — подождать и повторить . Клиент blend-ai ждёт до ~5 минут (150 попыток с шагом 2 с).

Ловушка отладки. recv(n) не обязан вернуть ровно n байт — он может вернуть меньше. Читай в цикле, пока не наберёшь нужное, иначе json.loads упадёт на обрезанном куске. В Python для сокета есть socket.MSG_WAITALL .

---

3. Установка: пошагово с нуля

Предварительные требования

⚠️ uv не входит в поставку. Если uv нет — поставь его первым:

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

⚠️ Пакета blend-ai нет на PyPI (проверено: NotFound ). Установка только из git-клона. Команда pip install blend-ai не сработает — не трать на неё время.

Шаг 1 — скачать MCP-сервер

git clone https://github.com/HoldMyBeer-gg/blend-ai.git
cd blend-ai
uv pip install -e .

Эквивалент через venv, если uv использовать не хочется:

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e .

Зависимости: mcp>=1.26.0 , pydantic>=2.0 . Точка входа — blend-ai → blend_ai.server:main .

Шаг 2 — установить аддон в Blender

Способ А (рекомендуемый) — из релиза:

1. Скачать blend_ai-1.3.0.zip : https://github.com/HoldMyBeer-gg/blend-ai/releases/download/v1.3.0/blend_ai-1.3.0.zip (все релизы: https://github.com/HoldMyBeer-gg/blend-ai/releases )
2. Blender → Edit → Preferences → Get Extensions → стрелка ▾ справа сверху → Install from Disk…
3. Выбрать скачанный .zip .
4. Включить галочку blend-ai в списке расширений.

Способ Б — симлинк на клон (удобно для разработки):

# Windows (запускать от имени администратора!)
mklink /D "%APPDATA%\Blender Foundation\Blender\<ver>\extensions\user_default\blend_ai" "%cd%\addon"

# macOS
ln -s "$(pwd)/addon" ~/Library/Application\ Support/Blender/<ver>/extensions/user_default/blend_ai

# Linux
ln -s "$(pwd)/addon" ~/.config/blender/<ver>/extensions/user_default/blend_ai

<ver> — версия Blender, например 4.2 или 5.2 .

Способ В — вручную распаковать (когда нет прав на симлинк и не хочется UI): распаковать содержимое zip в %APPDATA%\Blender Foundation\Blender\<ver>\extensions\user_default\blend_ai\ так, чтобы внутри лежал __init__.py .

Шаг 3 — ВКЛЮЧИТЬ сервер в Blender (самый забываемый шаг)

Установка аддона ≠ запуск сервера. Это два разных действия.

1. В 3D-вьюпорте нажать N (открыть боковую панель).
2. Найти вкладку blend-ai (вертикальные иконки справа).
3. Проверить поле Port (по умолчанию 9876 ).
4. Нажать Start Server .

Должно появиться:

Server: Running (port 9876)

Если видишь Server: Stopped — сервер не запущен, агент работать не будет.

Порт задаётся per-scene. Поле Port привязано к текущей сцене ( scene.blendai_port ). Открыл другой .blend — проверь, что порт тот же, и что сервер всё ещё запущен.

⚠️ Сервер НЕ запускается автоматически при старте Blender. Это осознанное решение автора аддона. После каждого перезапуска Blender кнопку надо нажимать снова. Если агент «внезапно перестал работать» — с вероятностью 90% причина в этом.

Шаг 4 — настроить клиента (MCP)

Claude Code:

claude mcp add blend-ai -- uv run --directory /path/to/blend-ai blend-ai

Claude Desktop — claude_desktop_config.json :

{
  "mcpServers": {
    "blend-ai": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/blend-ai", "blend-ai"]
    }
  }
}

Пути конфига: macOS ~/Library/Application Support/Claude/claude_desktop_config.json , Windows %APPDATA%\Claude\claude_desktop_config.json .

Другой клиент (любой MCP-совместимый):

uv run --directory /path/to/blend-ai blend-ai
# или напрямую:
python -m blend_ai.server

⚠️ Запускать MCP-сервер надо не «руками в терминале», а через клиента — он сам поднимает процесс и общается с ним по stdio. Ручной запуск в терминале выглядит как «зависло» — это нормально, сервер ждёт JSON-RPC на stdin.

---

4. Проверка, что всё работает

Порядок диагностики — сверху вниз. Останавливайся на первой сломанной ступени.

Таблица типовых ошибок

Быстрый диагностический скрипт

Сохрани как check_blender.py и запусти — проверит всё разом:

import json, socket, struct, sys

HOST, PORT = "127.0.0.1", 9876

def recv_exactly(sock, n):
    buf = b""
    while len(buf) < n:
        chunk = sock.recv(n - len(buf))
        if not chunk:
            raise ConnectionError("Blender closed the connection")
        buf += chunk
    return buf

def send(command, params=None, timeout=30.0):
    sock = socket.create_connection((HOST, PORT), timeout=timeout)
    try:
        msg = {"command": command}
        if params:
            msg["params"] = params
        payload = json.dumps(msg).encode("utf-8")
        sock.sendall(struct.pack(">I", len(payload)) + payload)
        length = struct.unpack(">I", recv_exactly(sock, 4))[0]
        return json.loads(recv_exactly(sock, length).decode("utf-8"))
    finally:
        sock.close()

if __name__ == "__main__":
    try:
        r = send("get_scene_info")
        if r.get("status") == "ok":
            info = r["result"]
            objs = info.get("objects", [])
            print(f"OK  scene='{info.get('scene_name')}'  objects={len(objs)}")
            for o in objs[:10]:
                print(f"    {o['type']:<8} {o['name']}")
            if len(objs) > 10:
                print(f"    ... and {len(objs)-10} more")
        else:
            print("Blender replied:", r)
    except ConnectionRefusedError:
        print("FAIL  Nothing listening on 127.0.0.1:9876.")
        print("      -> open Blender, press N, blend-ai tab, 'Start Server'")
        sys.exit(1)
    except socket.timeout:
        print("FAIL  Timeout. Blender may be rendering or in a modal operator.")
        sys.exit(1)

---

5. Команды: все 175

Полный список с описанием параметров — в COMMANDS.md . Краткая карта — ниже.

⚠️ Список команд не надо помнить. Отправь заведомо неверную команду — сервер вернёт ошибку с полным актуальным списком:

Unknown command: 'xxx'. Available commands: ['add_annotation_layer', ...]

Это самый надёжный способ узнать, что доступно в конкретной сборке.

Карта по областям

Первые команды, которые стоит вызвать

{"command": "get_scene_info"}                    // что вообще есть в сцене
{"command": "list_objects"}                      // список объектов
{"command": "list_materials"}                    // список материалов
{"command": "get_installed_extensions"}          // какие аддоны стоят
{"command": "get_object_info", "params": {"object_name": "Cube"}}

---

6. execute_code — песочница (главный инструмент)

Одна команда заменяет собой почти всё остальное: выполняет произвольный Python внутри Blender с полным доступом к bpy .

{"command": "execute_code", "params": {"code": "import bpy\nprint(len(bpy.data.objects))"}}

Что возвращает:

{"status": "ok", "result": {"output": "16", "success": true}}

Всё, что код напечатал через print() , попадает в result.output . Если код упал — вернётся RuntimeError с текстом ошибки и всем выводом до падения .

Что РАЗРЕШЕНО

bpy , bmesh , mathutils , math , json , random , collections , itertools , re — и вообще всё, кроме списков ниже.

Что ЗАПРЕЩЕНО (жёстко, на уровне песочницы)

Заблокированные модули (импорт падает с ImportError ):

os, subprocess, socket, shutil, sys, ctypes, importlib, pathlib, signal,
multiprocessing, pickle, shelve, tempfile, http, urllib, ftplib, smtplib,
xmlrpc, code, codeop, compileall, webbrowser, antigravity, turtle, tkinter

Удалённые встроенные функции : __import__ , exec , eval , compile , open , globals , locals , vars , input , breakpoint , exit , quit , help , memoryview .

Практические следствия (это ловит почти каждого)

Главная ловушка песочницы. os и sys заблокированы не случайно — это защита от выполнения произвольного кода. Если твой код начинается с import os — он упадёт целиком, причём сообщение будет про конкретный модуль, а не про то, что ты хотел. Пиши код без os / sys с самого начала.

Приём: передавай код файлом, а не строкой

Если код многострочный, экранировать его в JSON руками — мучение, и легко получить невнятное Expecting property name enclosed in double quotes . Лучше так:

# params.json
{"code": "import bpy\nfor o in bpy.data.objects:\n    print(o.name)"}

python blender_cmd.py execute_code @params.json

---

7. Грабли, которые стоят часа отладки

Здесь собрано только то, что проверено на практике и что реально ломает работу.

7.1 Физика (rigid body / cloth / fluid) НЕ симулируется

Это самая дорогая ловушка в репозитории.

Команды add_rigid_body , add_cloth_sim , add_fluid_sim , bake_physics выполняются без ошибок , конфигурация читается назад корректной (substeps=10, solver_iterations=10, time_scale=1.0, кэш 1..250), bake_physics даже возвращает is_baked: True — но объекты не двигаются ни на одном кадре , и после бейка в них нет ни animation_data , ни action.

Вывод: не проектируй рабочий процесс вокруг физических солверов. Движение делай ключевыми кадрами, драйверами или geometry nodes. Если нужна гравитация — считай параболу по кадрам в Python и ставь ключи. Это предсказуемо и видно глазами.

Как это было установлено: ключевые кадры на тех же объектах и тех же кадрах движение дают (z 9.0 → 4.32 → 2.0 → 1.09 → 1.0), а rigid body — нет. Значит канал set_frame рабочий, проблема именно в солвере.

7.2 Action.fcurves больше нет (Blender 5.x)

Старый путь action.fcurves падает с AttributeError . Актуальный:

action.layers[0].strips[0].channelbag(action.slots[0]).fcurves

Все старые примеры из интернета и большинство документации — устарели.

7.3 obj.rigid_body = None — read-only

Снять физическое тело присваиванием нельзя, будет AttributeError: ... is read-only . Только оператором, с активным и выделенным объектом:

bpy.ops.rigidbody.object_remove()

7.4 Рендер блокирует всё остальное

Во время рендера главный поток занят, сервер отвечает status: "busy" . Если нужно заниматься чем-то ещё — execute_code в это время не пройдёт. Жди или сбрасывай reset_render_guard .

7.5 Модальные операторы блокируют сервер

Если пользователь ушёл в sculpt/edit mode или запустил модальный оператор ( Ctrl+R , G , S ) и не завершил — сервер не может выполнить команду, будет таймаут. Лечение: Esc в Blender. В скриптах оборачивай в bpy.ops.object.mode_set(mode='OBJECT') .

7.6 Обновление аддона: обязательно полный перезапуск Blender

Фоновый TCP-поток переживает Reload Scripts . Поэтому после обновления аддона: выключить сервер → выключить/удалить аддон → полностью закрыть Blender → запустить заново → включить аддон. Иначе получишь старый код вперемешку с новым.

При разработке аддона помогает то, что при disable/enable аддон сам чистит кэш субмодулей ( _purge_submodules_from_cache ) — но это не спасает от старого потока.

7.7 Порт привязан к сцене, а не к Blender

scene.blendai_port — свойство сцены. Переключил .blend — проверь порт и статус сервера.

---

8. Рабочий цикл агента

Проверенный порядок действий — от него меньше всего сюрпризов:

1. get_scene_info                    # осмотреться, понять что есть
2. (сделать изменения)               # команды или execute_code
3. capture_viewport → прочитать PNG  # ПОСМОТРЕТЬ на результат
4. (если плохо) вернуться к шагу 2
5. render_image                      # финальный результат
6. save_file                         # сохранить, если нужно

Правило: всегда смотри на результат

Не верь, что команда сработала, если не видел картинку. Типичный сценарий провала: команда вернула status: ok , а на экране ничего не изменилось (объект за камерой, материал не назначен, модификатор не применён).

{"command": "capture_viewport", "params": {"filepath": "C:/tmp/check.png", "width": 1280, "height": 720}}

Ответ даёт путь к PNG — прочитай файл глазами (умеющие модели читают изображения). Только после этого считай шаг выполненным.

Уборка за собой

Если создавал временные объекты для проверки гипотезы — удали их в конце и верни сцену в исходное состояние. Пользователь смотрит на тот же вьюпорт, что и ты.

---

9. Где что лежит (пути)

Аддон (по версиям Blender)

Внутри: __init__.py , server.py , dispatcher.py , thread_safety.py , render_guard.py , ui_panel.py , blender_manifest.toml , handlers/ (25 файлов — по областям).

MCP-сервер (клон)

blend-ai/
├── addon/                  # исходники аддона (то, что симлинкуется в Blender)
├── src/blend_ai/
│   ├── server.py           # точка входа, FastMCP("blend-ai"), transport="stdio"
│   ├── connection.py       # TCP-клиент; DEFAULT_HOST/PORT здесь
│   ├── tool_registry.py
│   ├── tools/              # 24 модуля — обёртки MCP над командами
│   ├── resources/          # MCP resources
│   └── prompts/            # готовые промпты-воркфлоу
├── tests/                  # ~1190 тестов
└── pyproject.toml

---

10. Ссылки

---

Файлы в этом репозитории

---

Проверено на Blender 5.2.1 LTS + blend-ai v1.3.0, сентябрь 2026. Версии аддона и клиента должны совпадать — смешивание версий даёт трудноуловимые сбои.