Как связать llama.cpp и Blender через MCP для генерации 3D-сцен

Связка llama.cpp и Blender через MCP позволяет управлять 3D-сценой командами естественного языка. Локальная модель запускается через llama-server, MCP передает ей описание доступных инструментов, а Blender выполняет разрешенные операции через аддон и Python API.

Архитектура состоит из нескольких слоев: модель планирует действие, MCP-клиент или прокси передает вызов, MCP-сервер публикует инструменты Blender, аддон принимает запрос внутри приложения, а Blender меняет сцену. LLM не редактирует файл .blend напрямую и не получает полный контроль над программой без явно подключенных инструментов.

Для первого запуска лучше выбрать короткую проверяемую задачу: очистить сцену, добавить куб, изменить его координаты, назначить материал и сохранить копию файла. Параметр --ui-mcp-proxy нужно использовать только в тех сборках llama.cpp, где он присутствует в выводе llama-server --help или описан в документации конкретного релиза. Синтаксис подключения MCP зависит от версии llama.cpp и выбранной реализации Blender MCP.

Как работает связка llama.cpp, Blender и MCP

Роли компонентов: модель планирует, MCP передает, Blender исполняет

llama.cpp отвечает за локальный запуск LLM в формате GGUF. Компонент llama-server поднимает HTTP-интерфейс, через который клиент отправляет запросы модели и получает ответы. При поддержке tools модель может вернуть не обычный текст, а структурированный вызов инструмента с аргументами.

MCP, Model Context Protocol, задает общий формат обнаружения и вызова таких инструментов. MCP-сервер для Blender публикует операции, например добавление объекта, изменение трансформации, назначение материала или сохранение сцены. MCP-клиент либо прокси соединяет модель с этим сервером.

Внутри Blender работает аддон или другой мост. Он принимает запрос, проверяет его формат и вызывает разрешенную функцию через Blender Python API. Результат операции возвращается по той же цепочке, чтобы модель могла продолжить сценарий или сообщить об ошибке.

Полезно разделять четыре понятия:

• Модель интерпретирует текст и выбирает инструмент.
• llama-server обслуживает запросы к локальной LLM.
• MCP-сервер описывает доступные действия и передает их исполнителю.
• Blender и аддон выполняют операции над открытой сценой.

Об архитектуре MCP и механике подключения инструментов можно прочитать в отдельном разборе как MCP подключает ИИ-агентов к инструментам.

Что реально можно автоматизировать в первой версии пайплайна

Начальная конфигурация должна решать одну операцию за один вызов. Подходящие тесты:

• удалить объекты из текущей сцены;
• добавить куб, сферу или плоскость;
• задать координаты, масштаб и угол поворота;
• создать простой материал и назначить его объекту;
• добавить камеру и источник света;
• сохранить сцену в новый файл .blend.

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

Что потребуется для llama.cpp Blender MCP

llama.cpp и модель: что проверить до запуска сервера

Понадобятся сборка или релиз llama.cpp с доступным llama-server, GGUF-файл модели, Blender, MCP-сервер для Blender, аддон или мост, а также отдельное Python-окружение для серверных зависимостей.

До настройки MCP проверьте четыре пункта:

• путь к GGUF-файлу и права на чтение;
• совместимость модели с имеющимися RAM и VRAM;
• chat template, который использует выбранная модель;
• поддержку tool calls в модели и клиенте.

Запущенный HTTP-сервер сам по себе не означает, что модель умеет вызывать инструменты. В ответе может появляться обычный текст с предложением выполнить Python-код. Это другой сценарий, требующий отдельного исполнителя и дополнительных ограничений.

Версию Blender, релиз llama.cpp, модель и MCP-сервер нужно фиксировать вместе. Обновление одного слоя иногда меняет формат сообщений, параметры запуска или поведение аддона.

Blender, аддон и MCP-сервер: где проходит граница ответственности

Внешний MCP-сервер публикует набор tools. Он может работать как отдельный процесс и общаться с Blender через локальный порт, WebSocket, stdio или другой транспорт, который описывает конкретный проект. Аддон устанавливается в Blender через настройки приложения, активируется и получает параметры соединения.

Нельзя заранее считать, что любой MCP-сервер поддерживает один и тот же способ подключения. В README выбранного репозитория нужно сверить:

• команду установки;
• команду запуска;
• версию Python;
• транспорт и адрес подключения;
• названия инструментов;
• параметры аддона в Blender.

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

Изолированное Python-окружение для MCP-зависимостей

Создайте отдельное виртуальное окружение для MCP-сервера. Python, встроенный в Blender, имеет собственный набор пакетов и не должен без необходимости использоваться для внешнего сервера.

python -m venv .venv

# Linux и macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

python -m pip install --upgrade pip
pip install -r requirements.txt
pip freeze > requirements-lock.txt

Названия файлов и команда установки зависят от репозитория. Если проект предоставляет lock-файл, используйте его. Если сервер требует отдельную версию mcp, зафиксируйте ее в файле зависимостей и сохраните вывод pip freeze.

Зачем llama-server нужен --ui-mcp-proxy

Какая команда запуска llama-server нужна в вашем релизе

Простой запуск llama-server поднимает API модели. Для работы с MCP требуется дополнительный слой, который передает модели описания инструментов и маршрутизирует tool calls. В некоторых вариантах интеграции эту задачу связывают с параметром --ui-mcp-proxy.

Универсальной команды для всех сборок нет. Сначала выполните:

llama-server --help

Если текущий релиз документирует --ui-mcp-proxy, используйте его синтаксис и адрес MCP-прокси. Общий шаблон выглядит так:

llama-server \
  -m /path/to/model.gguf \
  --host 127.0.0.1 \
  --port <порт_llama_server> \
  --ui-mcp-proxy <адрес_или_параметры_прокси>

В Windows плейсхолдеры и переносы строк нужно заменить синтаксисом командной оболочки. Не копируйте этот шаблон как готовую команду: точное значение параметра, формат адреса и наличие самого флага определяет используемая сборка.

Если --ui-mcp-proxy отсутствует в справке, это не доказывает неисправность Blender. В такой версии MCP может подключаться через конфигурацию клиента, WebUI или отдельный процесс. Описание MCP-поддержки в llama.cpp и варианты работы с локальными агентами собраны в материале о поддержке MCP в llama.cpp.

Как проверить, что инструменты Blender обнаружены

Проверяйте цепочку до отправки команды на изменение сцены. В интерфейсе или API-клиенте должен отображаться список зарегистрированных MCP tools. Названия и поля зависят от сервера, поэтому ориентируйтесь на его документацию.

Одновременно проверьте:

• лог запуска MCP-сервера;
• лог llama-server;
• активный статус аддона в Blender;
• адреса и порты всех процессов;
• сырой ответ API, если модель не делает tool call.

Пустой список инструментов обычно указывает на ошибку транспорта, прокси или конфигурации. Наличие tools при текстовом ответе модели чаще связано с chat template, возможностями модели или форматом запроса.

Конфликт mcp v2: почему иногда фиксируют mcp==1.29.1

Как распознать несовместимость версии, а не ошибку Blender

Python-пакет mcp меняет API между ветками. MCP-сервер, написанный под одну версию, может завершаться сразу после запуска с ошибками импорта, отсутствующих атрибутов или несовпадающих сигнатур.

К признакам конфликта зависимостей относятся:

• ImportError и ModuleNotFoundError при старте;
• сообщения об отсутствующих классах или функциях;
• ошибки сериализации протокольных сообщений;
• сбой при создании транспорта или MCP-сессии;
• различия в формате списка tools и аргументов вызова.

Ошибка Blender выглядит иначе: аддон не активируется, не может подключиться к порту, пишет сообщения в Blender Console или получает некорректную команду уже после успешного старта MCP-сервера. Полный traceback помогает разделить эти случаи.

Как фиксировать mcp==1.29.1 без поломки остального окружения

Если README, lock-файл или issue конкретного Blender MCP-сервера прямо требуют mcp==1.29.1, установите пакет в отдельное venv:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install "mcp==1.29.1"
pip show mcp
pip freeze > requirements-lock.txt

Порядок установки нужно сверить с требованиями проекта. Если requirements.txt уже фиксирует совместимую версию, ручная переустановка может создать новый конфликт. Команда pip show mcp должна показать ожидаемую версию в активном окружении.

Фиксация mcp==1.29.1 подходит для сервера, которому нужна именно эта ветка API. Она не служит универсальным исправлением любой ошибки MCP. Без подтверждения из документации проекта сначала сверяйте версии Python, MCP-сервера и транзитивных пакетов.

Пошаговый запуск: от llama-server до первой 3D-сцены в Blender

Шаг 1. Запустите MCP-сервер и подключите Blender-аддон

Активируйте виртуальное окружение и запустите MCP-сервер командой из README выбранного проекта. Не подставляйте произвольные флаги: у разных серверов отличаются точки входа и параметры.

source .venv/bin/activate
python <команда_запуска_MCP-сервера>

В Blender откройте настройки дополнений, установите архив аддона, включите его и укажите транспорт, адрес или порт. После подключения контрольная точка выглядит так: процесс MCP-сервера работает, аддон активен, а в Blender Console нет ошибки соединения.

Шаг 2. Запустите llama-server и подключите MCP-прокси

Запустите llama-server с путем к GGUF-модели, локальным хостом и портом. Параметр --ui-mcp-proxy добавляйте только после проверки справки текущей сборки.

llama-server \
  -m /path/to/model.gguf \
  --host 127.0.0.1 \
  --port <порт>

# Вариант с прокси, только если он поддерживается релизом
llama-server \
  -m /path/to/model.gguf \
  --host 127.0.0.1 \
  --port <порт> \
  --ui-mcp-proxy <параметры_из_документации>

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

Шаг 3. Отправьте безопасную тестовую команду на создание сцены

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

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

Конкретный JSON для tool call зависит от клиента и MCP-сервера. Публиковать его без подтвержденной схемы инструмента нельзя: у одного проекта операция может называться add_object, у другого использовать единый инструмент выполнения сцены.

Перед запуском убедитесь, что открыта копия проекта. Для первого теста достаточно одного объекта и одной трансформации. Если команда прошла, модель должна получить ответ об успешном выполнении, а Blender показать куб в Outliner и в окне 3D-вида.

Шаг 4. Проверьте результат в Blender и зафиксируйте рабочую конфигурацию

Проверьте имя объекта, координаты, масштаб, активную сцену и путь сохранения. Ошибки выполнения смотрите в Blender Console и журнале MCP-сервера.

После успешного теста запишите:

• версию Blender;
• версию и способ сборки llama.cpp;
• имя и параметры GGUF-модели;
• версию MCP-сервера;
• версию Python;
• версию пакета mcp;
• команду запуска и настройки аддона.

Сохраните отдельный файл зависимостей и конфигурацию запуска. Это сократит время восстановления после обновления любого компонента.

Типовые проблемы llama.cpp Blender MCP и порядок диагностики

MCP-сервер не запускается или завершается сразу

Начните с активного окружения: выполните which python в Linux и macOS или where python в Windows. Затем проверьте версию Python, установленные пакеты и полный traceback.

python --version
python -m pip show mcp
python -m pip freeze

Сверьте команду запуска с README сервера. Ошибки импорта и несовпадение сигнатур проверяйте в контексте версии mcp. Если проект требует mcp==1.29.1, закрепите пакет только в его отдельном окружении.

llama-server не видит инструменты Blender

Проверьте доступность MCP-сервера, адреса, порты и транспорт. Затем сверяйте синтаксис параметров текущего llama-server с его справкой. Отдельно просмотрите лог прокси: соединение с llama-server и соединение с Blender могут проходить через разные настройки.

Если --ui-mcp-proxy отсутствует в вашей сборке, ищите предусмотренный релизом способ подключения MCP. Не добавляйте неизвестный флаг наугад: сервер завершится до обработки первого запроса.

Модель отвечает текстом, но не вызывает инструмент

Проверьте поддержку tool calls выбранной моделью, chat template и передачу схемы tools. Запрос сформулируйте однозначно: укажите объект, действие и параметры.

Для диагностики полезен сырой ответ API. Если в нем нет структурированного вызова, сеть и Blender могут работать исправно. Причина находится на уровне модели, шаблона чата или формата запроса.

Команда дошла до Blender, но сцена изменилась не так

Сверьте аргументы tool call с фактической схемой инструмента. Посмотрите Blender Console, активную сцену и контекст, в котором выполнялся Python-код.

Работайте с копией .blend, ограничивайте набор разрешенных операций и разбивайте длинный сценарий на этапы. Запрос на «полностью готовую сцену» сложнее проверить, чем последовательность из добавления объектов, настройки материалов, камеры и сохранения.

Ограничения связки и когда она действительно полезна

Подходящие сценарии: прототипы, шаблоны и повторяемые операции

Связка хорошо подходит для процедур, где результат можно проверить по конкретным параметрам:

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

Локальный запуск дает контроль над данными и не требует отправлять сцену во внешний сервис. Цена этого контроля, настройка модели, зависимостей, MCP-сервера и прав доступа. Сама автоматизация не гарантирует художественный результат и не устраняет необходимость проверять сцену.

Где нужен ручной контроль

LLM может неверно понять единицы измерения, выбрать не тот объект, вызвать неподходящий инструмент или сформировать некорректные параметры. Изменения Blender Python API между версиями добавляют еще один источник несовместимости.

Ограничьте инструменты минимальным набором, который нужен для задачи. Запрашивайте подтверждение перед удалением объектов, массовым изменением сцены и перезаписью файла. Храните резервную копию .blend и сначала тестируйте команды на отдельной сцене.

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

Подписаться на канал