Blender for Codex — 1.3.1

Открытый проект: приветствуются участие в разработке, сообщения об ошибках и pull requests. Ближайшие задачи — в плане развития.

Локальная интеграция Codex ↔ Blender: MCP-сервер, дополнение Blender, навык агента, установщик и диагностика. Это адаптация открытого сервера ahujasid/blender-mcp, как в плагине Kimi. Лицензия MIT; версии исходников зафиксированы в UPSTREAM.json. Это сторонний проект.

Возможности

• Чтение сцены, объектов, материалов и параметров.

• Моделирование, материалы, свет, камеры и анимация через Python/bpy.

• Просмотр сцены, рендеринг, открытие/сохранение .blend и импорт/экспорт через bpy.

• Дополнительные интеграции ресурсов upstream. Их аккаунты, тарифы и ключи настраиваются отдельно; в этом комплекте они не проверялись.

Основная работа происходит локально: Codex → stdio MCP → 127.0.0.1:9876 → Blender. Телеметрия upstream принудительно отключена в launcher. Сам Codex продолжает работать по своим настройкам; это не автономная локальная модель. Выполнение bpy имеет права процесса Blender на файлы компьютера. Дополнение слушает локальное соединение без отдельного пароля; не публикуйте этот порт в сеть.

Related MCP server: Blender MCP Link

Установка на Windows

Установка в список «Плагины»

codex plugin marketplace add blend3dweb/codex-blender-mcp-plugin
codex plugin add codex-blender-mcp@blend3dweb

Каталог появится под именем Blend3DWeb, плагин — Blender for Codex. GitHub-репозиторий публичный; это пользовательский marketplace, не публикация в общем каталоге OpenAI.

После установки подготовьте Python-окружение именно установленной копии. Если раньше сервер был добавлен отдельно через codex mcp add, сначала удалите дублирующую ручную запись командой codex mcp remove codex-blender — установленный плагин предоставляет свой сервер с этим именем. Затем:

$server = (codex mcp get codex-blender --json | ConvertFrom-Json).transport
$env:PLUGIN_DATA = $server.env.PLUGIN_DATA
python (Join-Path $server.env.PLUGIN_ROOT 'scripts/setup.py')
Remove-Item Env:PLUGIN_DATA

Окружение хранится в постоянном PLUGIN_DATA, отдельно от версионного кэша. Установите дополнение Blender по шагам ниже и перезапустите Codex. Не запускайте --register-codex при установке через marketplace: это альтернативный способ подключения.

Альтернатива: только MCP через CLI

Нужны Python 3.10+ и Blender. Проверенная версия Blender указана в VALIDATION.md.

1. Распакуйте папку в постоянное место. Откройте там PowerShell.

2. Подготовьте окружение и добавьте сервер в Codex:

   python scripts/setup.py --register-codex

   Установщик создаёт .venv внутри комплекта. Добавляет только MCP-запись codex-blender; существующую запись с таким именем не перезаписывает. Перед изменением config.toml создаёт резервную копию. При конфликте используйте --name blender-local. Для подготовки без изменения настроек Codex: python scripts/setup.py.

3. В Blender откройте Edit → Preferences → Add-ons → меню → Install from Disk. Выберите assets/blender_mcp.py, включите MCP for Blender.

4. В 3D Viewport нажмите N, вкладка MCP for Blender, проверьте Start MCP Server. В текущем дополнении также предусмотрен автозапуск.

5. Полностью перезапустите Codex. Попросите: «Проверь подключение к Blender и перечисли объекты сцены».

Для диагностики, когда другой MCP-клиент не подключён:

.\.venv\Scripts\python.exe scripts/check_connection.py

Диагностика читает сцену, не изменяет её. Отсутствующий Blender приводит к ошибке, а не к сообщению об успехе.

Комплект плагина

plugin.json, mcp.json и skills/ подготовлены в формате Agent Plugins для настольного клиента. Перед запуском сервера требуется выполнить setup в той папке, где установлен комплект. Загрузка ZIP через интерфейс плагинов отдельно не проверялась; проверенный путь подключения — локальный MCP через Codex CLI. Не подключайте одновременно MCP из манифеста и дублирующую запись из config.toml.

Установка через CLI регистрирует MCP-сервер, но не устанавливает отдельно упакованный навык в каталог навыков Codex. Инструкции навыка доступны при установке комплекта как плагина; сам сервер также содержит инструкции для работы со сценой.

Удаление и восстановление

codex mcp remove codex-blender удаляет созданную MCP-запись (если выбрали другое имя, укажите его). В Blender отключите и удалите установленное дополнение. После этого папку комплекта можно удалить. Не восстанавливайте старый config.toml целиком, если после установки появились другие настройки: сохраните их и удалите только эту запись.

Состав и воспроизводимость

• assets/blender_mcp.py — дополнение upstream без изменений.

• vendor/blender_mcp/ — зафиксированные исходники сервера upstream без изменений; лицензия в vendor/LICENSE.

• scripts/ — launcher, установщик и проверка MCP.

• requirements.lock.txt — проверенные версии зависимостей Python; первая установка требует доступа к PyPI.

• skills/blender-mcp/SKILL.md — инструкции Codex.

• VALIDATION.md — фактически выполненные проверки и ограничения.

Формат подключения: официальная документация MCP. Формат комплекта: официальная документация плагинов.

Версия 1.1: студийные операции

Добавлены 11 специализированных навыков и два MCP-инструмента: studio_capabilities описывает параметры, studio_action выполняет операцию над явно заданными объектами. Поддержаны inspect, bevel, subdivide, decimate, remesh, sculpt_deform, uv_smart, material, keyframe, turntable, rigid_body, cloth, render_settings, save_copy. Новые инструменты находятся в scripts/studio_tools.py и scripts/studio_ops.py; исходники upstream не изменены.

Для ручного подключения через CLI навыки нужно дополнительно скопировать из skills в каталог навыков Codex без перезаписи существующих папок. Установка всего пакета через интерфейс плагинов отдельно не проверялась.

Версия 1.2: пространственный осмотр

Добавлены spatial_capabilities, spatial_inspect и навык blender-spatial-inspection. Доступны связность сетки, координаты и связи элементов, плоские сечения, выборочные расстояния между поверхностями и сопоставление ориентиров через камеру. Для изображений используется уже существующий look с несколькими ракурсами, Wireframe и X-Ray.

Инструкция по новым возможностям. Проверено 21 геометрической проверкой, 11 проверками через MCP и 19 регрессионными проверками студийных операций в Blender 5.2.2 LTS. Пакет содержит 13 инструментов и 13 навыков. Автоматическое восстановление по фото и проверка самопересечений не реализованы.

Версия 1.3: обратимые локальные правки

Добавлены edit_capabilities и edit_session: снимок координат, локальное смещение с плавным спадом, численное сравнение и откат с защитой посторонних изменений. Всего 15 MCP-инструментов и 13 навыков. Инструкция, план развития, результаты проверки.

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

Разработка и тесты

Запускайте тесты из корня репозитория. Скрипты tests/test_*_ops.py используют bpy и выполняются внутри Blender, а не обычным pytest.

python scripts/test_blender.py --blender "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe"
.\.venv\Scripts\python.exe tests/test_mcp.py --blender "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe"

Первый запуск проверяет геометрию в отдельных фоновых процессах с factory startup. Второй запускает отдельный интерактивный Blender для проверки MCP и снимков viewport, порт по умолчанию 19877; нужно графическое окружение. Основная сцена пользователя и его настройки не используются. Логи и изображения сохраняются в игнорируемый test-output/.