Blender MCP

Инструмент, позволяющий Claude AI напрямую управлять Blender 3D через протокол MCP (Model Context Protocol).

С помощью команд на естественном языке Claude может автоматически создавать, изменять, удалять объекты в сцене Blender и выполнять Python-код.

Принцип работы

Claude Desktop
     │ MCP (stdio / HTTP·SSE)
     ▼
MCP Server (Python)          ← 이 저장소
     │ TCP Socket :9999
     ▼
Blender Add-on (Python)      ← 이 저장소
     │ bpy API
     ▼
Blender 씬

Related MCP server: BlenderMCP

Требования

Установка

Шаг 1 — Клонирование репозитория

git clone https://github.com/nowcika/blender_mcp.git
cd blender_mcp

Шаг 2 — Установка зависимостей MCP-сервера

pip install -r requirements.txt

Содержимое requirements.txt: mcp>=1.0.0

Шаг 3 — Установка аддона Blender

Сначала упакуйте папку addon/ в zip-архив:

# 터미널에서 프로젝트 루트 위치에서 실행
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

Теперь установите его в Blender:

1. В верхнем меню Blender нажмите Edit (Правка)

2. Нажмите Preferences (Настройки)

3. В левой части окна настроек нажмите Add-ons (Аддоны)

4. В правом верхнем углу нажмите на стрелку выпадающего списка (⌄) → Install from Disk (Установить с диска)

5. Выберите созданный файл blender_mcp_addon.zip

6. Нажмите кнопку Install Add-on (Установить аддон)

7. Активируйте аддон, установив галочку слева от пункта "Blender MCP" в списке

Шаг 4 — Запуск сокет-сервера в Blender

Что такое 3D-вьюпорт? При открытии Blender вы видите большое 3D-пространство в центре. Это основная рабочая область для размещения и манипуляции объектами. Что такое боковая панель (Sidebar)? Если нажать клавишу N на клавиатуре внутри 3D-вьюпорта, справа откроется панель. Это и есть боковая панель.

1. Наведите курсор мыши на область 3D-вьюпорта в центре Blender

2. Нажмите клавишу N на клавиатуре → справа откроется боковая панель

3. Нажмите на вкладку MCP в верхней части боковой панели

4. Нажмите кнопку Start MCP Server

5. Когда статус над кнопкой изменится на Running, всё готово

Если клавиша N не работает: Убедитесь, что курсор мыши находится внутри 3D-вьюпорта. В Blender горячие клавиши зависят от положения мыши.

Порт по умолчанию: 9999. Чтобы изменить его, настройте переменную окружения:

BLENDER_MCP_PORT=9998  # Blender 실행 전 설정

Интеграция с Claude Desktop (stdio — рекомендуется)

Добавьте следующее содержимое в файл claude_desktop_config.json.

Расположение файла:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blender": {
      "command": "python3",
      "args": ["-m", "server", "--transport", "stdio"],
      "cwd": "/절대경로/blender_mcp"
    }
  }
}

Замените /абсолютный/путь/к/blender_mcp на реальный путь клонирования. Пример для Windows: "cwd": "C:\\Users\\yourname\\blender_mcp"

После настройки перезапустите Claude Desktop.

Интеграция с Claude Code (терминальный CLI)

Используется, если вы предпочитаете команду claude в терминале вместо Claude Desktop.

Способ 1 — Автоматическое распознавание в папке проекта (рекомендуется)

В этом репозитории содержится файл .mcp.json. Если запустить claude внутри папки blender_mcp, MCP-сервер будет зарегистрирован автоматически.

cd blender_mcp
claude        # .mcp.json을 자동으로 읽어서 blender MCP 활성화

Способ 2 — Глобальная регистрация для использования отовсюду

Введите в терминале, заменив /абсолютный/путь/к/blender_mcp на реальный путь:

claude mcp add --scope user blender python3 /절대경로/blender_mcp/start_server.py

Пример (Windows):

claude mcp add --scope user blender python3 C:/Users/yourname/blender_mcp/start_server.py

Проверка регистрации:

claude mcp list

Режим HTTP/SSE (удаленное подключение)

Используется для управления Blender с удаленного сервера, а не локально.

# MCP 서버를 HTTP 모드로 실행
python3 -m server --transport http --host 0.0.0.0 --port 8080

Настройка Claude Desktop:

{
  "mcpServers": {
    "blender": {
      "url": "http://서버IP:8080/sse"
    }
  }
}

Доступные инструменты MCP

При общении с Claude следующие инструменты активируются автоматически.

Пример использования

В чате Claude Desktop:

큐브 하나 만들어줘
→ Claude가 create_object 도구 호출 → Blender에 Cube 생성

방금 만든 큐브를 (3, 0, 1)로 이동하고 45도 회전해줘
→ Claude가 modify_object 호출 → 위치·회전 적용

현재 씬에 있는 모든 오브젝트 목록 알려줘
→ Claude가 get_scene_info 호출 → 오브젝트 목록 반환

Настройка переменных окружения

Устранение неполадок

Ошибка "Blender is not running"

• Убедитесь, что Blender запущен

• Убедитесь, что вы нажали кнопку Start MCP Server в N-панели → вкладка MCP в 3D-вьюпорте

• Убедитесь, что брандмауэр не блокирует порт 9999

Аддон не появляется в списке

• Убедитесь, что версия Blender 4.2 или выше (проверьте в Help (Справка) → About Blender (О Blender) в верхней части экрана)

• Файлы внутри папки addon/ должны находиться непосредственно в корне zip-архива. Переупакуйте их следующим образом:

# 올바른 압축 방법 (addon/ 폴더 안에서 실행)
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

Не удается подключиться к MCP-серверу

# 의존성 확인
pip show mcp

# 서버 직접 테스트 (stdio 대신 로그 확인용)
python3 -m server --transport http --port 8080
# http://localhost:8080/sse 접근해서 응답 확인

Структура проекта

blender_mcp/
├── addon/
│   ├── __init__.py           # Blender Add-on + 소켓 서버
│   ├── executor.py           # bpy 명령 실행기
│   └── blender_manifest.toml # Blender 5.x Extension 매니페스트
├── server/
│   ├── __init__.py           # MCP 서버 진입점 (stdio / HTTP)
│   ├── tools.py              # MCP 도구 6개 정의
│   └── blender_client.py     # Blender 소켓 클라이언트
├── requirements.txt
└── README.md

Лицензия

GPL-3.0-or-later