blender-lab-mcp-client

MCP-клиент, который общается по реальному сетевому протоколу официального MCP-аддона «Blender Lab» от Blender.org, предоставляя те же 27 инструментов, что и djeada/blender-mcp-server, — но работающий с blender.org/lab/mcp-server вместо собственного встроенного аддона этого проекта.

Почему это существует

Существуют (как минимум) два не связанных между собой проекта «Blender + MCP», которые совпадают по названию, порту по умолчанию и описанию:

1. djeada/blender-mcp-server — поставляет парный набор: собственный аддон Blender и Python-MCP-клиент, общающиеся по протоколу с разделителем строк {"id", "command", "params"} / {"success", "result"} через localhost:9876.

2. Официальный аддон Blender Lab (blender.org/lab/mcp-server, сопровождающий — «Blender Authors») — совершенно отдельный проект. Он также слушает localhost:9876, но поставляет только сторону аддона. Он общается запросами с нулевым байтом в качестве разделителя {"type": "execute", "code": ..., "strict_json": ...} и ответами {"status": "ok"|"error", "result": ...}, не имеет встроенного диспетчера именованных команд (просто выполняет сырой Python в bpy) и закрывает TCP-соединение после каждого запроса.

Если вы установите официальный аддон Blender Lab, но настроите MCP-клиент, указывающий на djeada/blender-mcp-server (например, через uvx blender-mcp-server), каждый вызов инструмента будет завершаться ошибкой примерно такого вида:

Extra data: line 1 column 51 (char 50)

или при следующем вызове:

Lost connection to Blender: Blender connection closed

Это не нестабильное соединение, не устаревший процесс и не ошибка Blender — это два несвязанных протокола, которые говорят мимо друг друга. Клиент djeada отправляет запрос, завершающийся переводом строки, который аддон никогда не распознаёт; аддон доводит клиента до тайм-аута, отправляет обратно небольшую ошибку с завершающим нулевым байтом, и readline() клиента спотыкается о посторонний нулевой байт сразу после JSON-объекта.

Этот пакет заново реализует каждый из исходных 27 MCP-инструментов, генерируя эквивалентный Python-код bpy и отправляя его через фактический протокол аддона Blender Lab, так что имена инструментов, параметры и поведение остаются прежними — меняется только формат передачи данных под капотом.

Установка

1. Установите официальный MCP-аддон Blender Lab в Blender (Правка → Настройки → Аддоны → поиск «MCP» или через платформу Extensions) и убедитесь, что он слушает 127.0.0.1:9876 (Настройки аддона → Запустить сервер).

2. Установите этот пакет:

   git clone https://github.com/A-to-PC/blender-lab-mcp-client.git
   cd blender-lab-mcp-client
   pip install -e .

3. Укажите вашему MCP-клиенту на него. Для конфигурации в стиле mcp.json:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "blender-lab-mcp-client"
       }
     }
   }

   Или запустите прямо из исходников без установки через uv:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "uv",
         "args": ["run", "--project", "/absolute/path/to/blender-lab-mcp-client", "blender-lab-mcp-client"]
       }
     }
   }

Справочник инструментов

Те же 27 инструментов, что и в исходном проекте, — см. справочник инструментов djeada/blender-mcp-server для полной таблицы (осмотр сцены, манипуляция объектами, материалы, рендеринг/экспорт, история, выполнение Python, асинхронные задания). Имена и параметры не изменены; отличается только транспорт под капотом.

Известные ограничения

• blender_python_exec_async / blender_job_status / blender_job_cancel / blender_job_list (только bridge-транспорт) имитируются как синхронные. Настоящий механизм отложенных заданий аддона требует, чтобы исполняемый код сам задавал вызываемый объект check_is_finished, что нецелесообразно синтезировать универсально из произвольного отправленного кода. Асинхронные вызовы в живой сессии Blender на самом деле выполняются синхронно и немедленно сообщаются как "succeeded". Для по-настоящему длительных операций (запекание физики, тяжёлые симуляции) используйте вместо этого transport="headless" — этот путь запускает отдельный фоновый процесс blender -b и не подвержен данному ограничению.

• Одно соединение на запрос. Аддон закрывает свой сокет после каждого ответа, поэтому этот клиент не может переиспользовать постоянное соединение — каждый вызов инструмента открывает новое TCP-соединение. Это соответствует реальной архитектуре аддона; это не трюк для производительности, который можно было бы «исправить» на стороне клиента.

• Протестировано на Blender 5.2 LTS с аддоном Blender Lab. Вспомогательный код для объектов/материалов использует стандартные вызовы bpy.ops.* и должен работать в любой свежей версии Blender, но не проверялся на матрице версий.

Авторство

Форк djeada/blender-mcp-server (лицензия MIT, автор — Адам Джелули) — поверхность MCP-инструментов (имена, параметры, описания) и транспорт фонового выполнения headless.py перенесены без изменений. Новыми являются только BlenderConnection из server.py и слой трансляции команд в код bpy, чтобы работать с протоколом официального аддона Blender Lab вместо собственного встроенного аддона исходного проекта.

Лицензия

MIT — см. LICENSE.