# Quick Start Guide: Запуск BlenderMCP с Claude Desktop
## Предварительные требования
- ✅ **Blender 3.0+** установлен
- ✅ **Python 3.10+** установлен
- ✅ **Claude Desktop** установлен
- ✅ **uv** package manager установлен
### Проверка uv
```bash
# Windows
uv --version
```
Если не установлен:
```bash
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
## Шаг 1: Установка Blender Addon
### 1.1. Найдите addon.py
Файл находится в: `D:\repos\blender-mcp\addon.py`
### 1.2. Установите addon в Blender
1. Откройте **Blender**
2. Перейдите: **Edit > Preferences > Add-ons**
3. Нажмите **Install...** (вверху справа)
4. Выберите файл `D:\repos\blender-mcp\addon.py`
5. **Включите** addon, поставив галочку рядом с "Interface: Blender MCP"
## Шаг 2: Запуск Blender Server
### 2.1. Откройте Blender sidebar
1. В **3D Viewport** нажмите **N** (если sidebar не видна)
2. Найдите вкладку **"BlenderMCP"**
3. Настройки по умолчанию:
- Port: **9876**
- PolyHaven: выключен (можно включить для asset библиотеки)
- Hyper3D: выключен (можно включить для AI генерации)
- Sketchfab: выключен (можно включить для моделей)
### 2.2. Запустите server
1. Нажмите **"Connect to Claude"**
2. Вы увидите сообщение в консоли: `BlenderMCP server started on localhost:9876`
**⚠️ ВАЖНО:** Оставьте Blender открытым и addon running!
## Шаг 3: Настройка Claude Desktop
### 3.1. Найдите конфигурационный файл
**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
Полный путь обычно:
```
C:\Users\<ВашеИмя>\AppData\Roaming\Claude\claude_desktop_config.json
```
### 3.2. Откройте конфиг
В Claude Desktop:
1. Нажмите **Settings** (⚙️)
2. Перейдите в **Developer**
3. Нажмите **Edit Config**
### 3.3. Добавьте BlenderMCP server
Замените содержимое на:
```json
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"blender-mcp"
]
}
}
}
```
**Или если уже есть другие серверы:**
```json
{
"mcpServers": {
"existing-server": {
"command": "...",
"args": [...]
},
"blender": {
"command": "uvx",
"args": [
"blender-mcp"
]
}
}
}
```
### 3.4. Сохраните и перезапустите Claude Desktop
1. **Сохраните** файл конфигурации
2. **Полностью закройте** Claude Desktop
3. **Откройте** Claude Desktop снова
## Шаг 4: Проверка подключения
### 4.1. Проверьте иконку инструментов
После запуска Claude Desktop вы должны увидеть **иконку молотка** (🔨) в интерфейсе.
Это означает, что MCP серверы подключены.
### 4.2. Протестируйте базовое подключение
Напишите Claude:
```
List all available Blender MCP tools
```
Или по-русски:
```
Покажи все доступные инструменты для Blender
```
**Ожидаемый результат:** Claude должен перечислить ~24 инструмента, включая:
- get_scene_info
- mesh_stats
- detect_topology_issues
- voxel_remesh
- quadriflow_remesh
- и другие...
### 4.3. Тест простой команды
```
Get information about the current Blender scene
```
**Ожидаемый результат:** JSON с информацией о сцене (объекты, материалы и т.д.)
## Шаг 5: Тестирование Retopology Tools
### Тест 1: Mesh Statistics
```
Create a default cube and give me detailed mesh statistics
```
**Ожидаемое поведение:**
1. Claude создаст cube (или использует существующий)
2. Вызовет `mesh_stats(active_only=true)`
3. Покажет статистику: вершины, рёбра, грани, tri/quad breakdown
### Тест 2: Topology Issues
```
Check the default cube for any topology issues
```
**Ожидаемое поведение:**
1. Claude вызовет `detect_topology_issues()`
2. Покажет отчёт (cube должен быть чистым, без проблем)
### Тест 3: Remeshing
```
Apply voxel remesh to the cube with voxel size 0.1
```
**Ожидаемое поведение:**
1. Claude вызовет `voxel_remesh(voxel_size=0.1)`
2. Mesh будет перестроен
3. Покажет old vs new face count
### Тест 4: Viewport Controls
```
Switch viewport to orthographic mode and align to front view
```
**Ожидаемое поведение:**
1. `set_view_projection(projection="ORTHO")`
2. `align_view_to_axis(axis="Y", side="POS")`
3. Viewport переключится в ortho front view
### Тест 5: Retopology Pipeline Prompt
```
Use the retopo_pipeline prompt to guide me through retopologizing a mesh
```
**Ожидаемое поведение:**
Claude загрузит retopo_pipeline prompt и предоставит пошаговое руководство.
## Troubleshooting
### ❌ "Could not connect to Blender"
**Причины:**
1. Blender не запущен
2. Addon не активирован
3. Server не запущен (не нажали "Connect to Claude")
4. Неправильный порт
**Решение:**
1. Откройте Blender
2. Проверьте addon в Preferences
3. Нажмите "Connect to Claude" в BlenderMCP sidebar
4. Проверьте консоль Blender на наличие ошибок
### ❌ Hammer icon не появляется в Claude
**Причины:**
1. Claude Desktop не перезапущен после изменения конфига
2. Ошибка в синтаксисе JSON конфига
3. uvx не установлен
**Решение:**
1. Полностью закройте Claude Desktop (через Task Manager если нужно)
2. Проверьте JSON syntax в конфиге (валидный JSON?)
3. Проверьте: `uvx --version` в терминале
4. Откройте Claude Desktop снова
### ❌ "First command doesn't work"
**Это нормально!**
Иногда первая команда может не пройти, но последующие работают. Просто попробуйте команду ещё раз.
### ❌ Timeout errors
**Причины:**
- Слишком сложная операция
- Blender завис
**Решение:**
1. Разбейте запрос на более простые шаги
2. Проверьте что Blender responsive
3. Перезапустите Blender addon если нужно
### ❌ Tools not found
**Решение:**
```bash
# Переустановите пакет
uvx --refresh blender-mcp
```
## Advanced: Локальная разработка
Если вы разрабатываете локально из `D:\repos\blender-mcp`:
### 1. Установите в dev mode
```bash
cd D:\repos\blender-mcp
pip install -e .
```
### 2. Обновите Claude config для dev
```json
{
"mcpServers": {
"blender-dev": {
"command": "python",
"args": [
"-m",
"blender_mcp.server"
],
"env": {
"PYTHONPATH": "D:\\repos\\blender-mcp\\src"
}
}
}
}
```
### 3. Или используйте прямой путь
```json
{
"mcpServers": {
"blender-dev": {
"command": "python",
"args": [
"D:\\repos\\blender-mcp\\main.py"
]
}
}
}
```
## Полезные команды для тестирования
### Базовые операции
```
# Информация о сцене
"What objects are currently in the Blender scene?"
# Создание объектов
"Create a UV sphere with 32 segments"
# Viewport screenshot
"Take a screenshot of the current viewport"
```
### Retopology Workflows
```
# Анализ mesh
"Analyze the topology of the active mesh and tell me if there are any issues"
# Voxel remesh
"Apply voxel remesh with voxel size 0.05 to clean up this mesh"
# QuadriFlow remesh
"Use QuadriFlow to retopologize this mesh to 5000 quad-dominant faces"
# Decimate
"Reduce this mesh to 50% of its current polycount"
# Mark edges
"Mark sharp edges at 30 degrees and UV seams at 60 degrees"
```
### Viewport & Inspection
```
# Ортографический режим
"Switch to orthographic view and show me the front view"
# Выравнивание
"Align the viewport to show the top view"
# Фреймирование
"Frame the selected object in the viewport"
```
### Guided Workflow
```
# Используйте retopo pipeline prompt
"Guide me through the complete retopology workflow for this mesh"
# Asset creation strategy
"What's the best way to create a realistic tree in Blender?"
```
## Логи и отладка
### Blender Console
1. В Blender: **Window > Toggle System Console**
2. Здесь вы увидите все команды и ошибки от MCP сервера
### Claude Desktop Logs
**Windows:**
```
%APPDATA%\Claude\logs\
```
Проверьте последние логи для ошибок MCP.
## Next Steps
После успешного подключения:
1. 📚 Прочитайте [Retopology Guide](README.md#retopology-guide) в README
2. 🏗️ Изучите [Architecture](ARCHITECTURE.md) для понимания структуры
3. 🎯 Попробуйте example workflows из README
4. 🔧 Экспериментируйте с разными retopo инструментами
## Support
- **Issues:** https://github.com/ahujasid/blender-mcp/issues
- **Discord:** https://discord.gg/z5apgR8TFU
- **Docs:** См. README.md, ARCHITECTURE.md, и RETOPO_IMPLEMENTATION.md
---
**Готово!** Теперь вы можете использовать Claude для управления Blender! 🎉
