Blender 2D MCP

AI-управляемое 2D-рисование и анимация для Blender 5.x через Model Context Protocol. Позволяет MCP-клиентам (Claude Desktop, Cursor, режим агента VS Code Copilot, …) создавать рисунки Grease Pencil, ключевые кадры, материалы и рендеры прямо в запущенном экземпляре Blender.

Построен на API GPv3 Blender (bpy.ops.grease_pencil.*, GreasePencilDrawing), по образцу ahujasid/blender-mcp.

flowchart LR
    A[MCP Client<br/>Claude / Cursor / VS Code] <-->|stdio / JSON-RPC| B[blender-2d-mcp<br/>FastMCP server]
    B <-->|TCP JSON<br/>localhost:9876| C[addon.py<br/>socket server in Blender]
    C -->|main thread| D[Grease Pencil API<br/>GPv3]

• addon.py — аддон Blender, встраивающий TCP-сервер JSON-команд. Команды ставятся в очередь и выполняются в главном потоке Blender через bpy.app.timers.

• src/blender_2d_mcp/server.py — FastMCP stdio-сервер, предоставляющий команды аддона как MCP-инструменты.

Требования

• Только Blender 5.2 LTS (аддон отказывается включаться на более старых сборках; используемый им API GPv3 специфичен для 5.2)

• Python ≥ 3.10 с mcp[cli] (устанавливается автоматически)

Related MCP server: Blender MCP Bridge

Установка

1. Установите аддон в Blender

1. В Blender: Правка > Настройки > Дополнения > Установить…

2. Выберите addon.py из этого репозитория.

3. Включите Интерфейс: Blender 2D MCP.

4. Откройте боковую панель (Вид > Боковая панель или нажмите N) → вкладка Blender2DMCP.

5. Нажмите Подключиться к MCP-клиенту (порт по умолчанию 9876). Оставьте Blender запущенным.

Совет: blender-2d-mcp --install-addon копирует addon.py в вашу папку «Загрузки» и выводит эти шаги.

2. Подключите MCP-клиента

Сервер привязывается только к localhost — для локального использования токен авторизации не нужен.

Вариант A — uvx (без установки):

uvx --from "g:\My Projects\blender-2d-mcp" blender-2d-mcp

Вариант B — редактируемая установка:

cd "g:\My Projects\blender-2d-mcp"
pip install -e .
blender-2d-mcp            # runs the stdio MCP server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"]
    }
  }
}

Cursor (.cursor/mcp.json) или универсальные stdio-клиенты:

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "C:\\Path\\To\\Python\\Scripts\\blender-2d-mcp.exe",
      "args": []
    }
  }
}

VS Code / GitHub Copilot Chat (.vscode/mcp.json — уже включён в этот репозиторий):

{
  "servers": {
    "blender-2d-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"],
      "env": {}
    }
  }
}

Альтернативно, если blender_2d_mcp установлен через pip в каком-либо окружении, используйте Python этого окружения: "command": "C:\\Path\\To\\Python\\python.exe", "args": ["-m", "blender_2d_mcp.server"].

Чтобы использовать: откройте Copilot Chat, переключите раскрывающийся список режимов на Agent, и инструменты Blender станут доступны (#blender-2d-mcp). Запускайте/останавливайте/перезапускайте сервер из палитры команд с помощью MCP: List Servers. Перезагрузите окно VS Code после редактирования mcp.json.

2D-холст

С помощью setup_2d_scene видовой экран переключается на ортографический вид спереди, поэтому плоскость рисования — мировая XZ:

Единицы измерения — метры (по умолчанию в Blender); кадр HD 1920×1080 при стандартном зуме камеры занимает примерно ±5 единиц по горизонтали.

Каталог инструментов

Типичный рабочий процесс

1. get_gp_scene_info + get_viewport_screenshot — посмотрите, что уже есть.

2. setup_2d_scene → create_gp_object, если начинаете с нуля.

3. Рисуйте с помощью gp_draw_shape / gp_draw_stroke; передавайте frame_number, чтобы разместить штрихи на ключевых позах (кадры создаются автоматически). Используйте gp_draw_strokes для пакетного рисования детальных изображений.

4. Заливка фигур: создайте материал с fill_alpha > 0, затем fill=True + fill_material.

5. Анимируйте «по два кадра» (ключевые позы каждые 2 кадра при 24 fps): копируйте позы с помощью gp_copy_frame, корректируйте через gp_transform_stroke, затем используйте gp_interpolate для промежуточных кадров. Добавьте модификатор NOISE для эффекта рисованной дрожи.

6. Рендерите с помощью render_animation(use_video=True) и опрашивайте get_render_status.

7. Всегда делайте скриншот после изменений, чтобы проверить результат визуально. Ошибки можно откатить через undo.

Разработка

pip install -e ".[dev]"
python -m pytest tests/ -v

Тестовый набор запускает TCP-транспорт аддона вне Blender, поднимая класс сервера через AST-трансформацию с фейковым bpy — установка Blender не требуется. Логику обработчиков, работающую с реальными данными Grease Pencil, необходимо проверять внутри Blender.

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

Лицензия

MIT