SketchupMCP — Интеграция Sketchup с протоколом Model Context Protocol

Изначально форк mhyrr/sketchup-mcp. Ответвление произошло на версии v0.0.1 с новым протоколом передачи данных (фрейминг с 4-байтовым префиксом длины), модульной архитектурой обработчиков, расширенными инструментами интроспекции / соединений / операций с ребрами, и полным покрытием модульными тестами как на Ruby, так и на Python. Опубликовано на PyPI как sketchup-mcp2 (оригинальный пакет sketchup-mcp является апстримом).

SketchupMCP подключает Sketchup к Claude AI через протокол Model Context Protocol (MCP), позволяя Claude напрямую взаимодействовать со Sketchup и управлять им. Эта интеграция позволяет выполнять 3D-моделирование, создание сцен и манипуляции в Sketchup с помощью подсказок.

Огромная благодарность Blender MCP за вдохновение и структуру.

Возможности

• Двусторонняя связь: Подключение Claude AI к Sketchup через TCP-сокет

• Манипуляция компонентами: Создание, изменение, удаление и трансформация компонентов в Sketchup

• Управление материалами: Применение и изменение материалов и цветов

• Инспекция сцены: Получение подробной информации о текущей сцене Sketchup

• Работа с выделением: Получение и манипуляция выделенными компонентами

• Выполнение Ruby-кода: Выполнение произвольного кода Ruby непосредственно в SketchUp для расширенных операций

Related MCP server: SketchupMCP

Компоненты

Система состоит из двух основных компонентов:

1. Расширение SketchUp (su_mcp/su_mcp/): модульный плагин на Ruby, который запускает TCP-сервер внутри SketchUp (core/, handlers/, helpers/).

2. MCP-сервер (src/sketchup_mcp/): модульный пакет на Python, построенный на FastMCP — tools.py предоставляет инструменты MCP, connection.py отвечает за постоянное TCP-соединение с 4-байтовым префиксом длины, config.py считывает переменные окружения SKETCHUP_MCP_*, errors.py выводит структурированные ошибки Ruby.

Установка

Python-пакеты

Мы используем uv, поэтому вам нужно выполнить brew install uv

Расширение Sketchup

1. Скачайте или соберите последний файл .rbz

2. В Sketchup перейдите в Window > Extension Manager

3. Нажмите "Install Extension" и выберите скачанный файл .rbz

4. Перезапустите Sketchup

Использование

Запуск соединения

1. В Sketchup перейдите в Extensions > SketchupMCP > Start Server

2. Сервер запустится на порту по умолчанию (9876)

3. Убедитесь, что MCP-сервер запущен в вашем терминале

Использование с Claude

Настройте Claude для использования MCP-сервера, добавив следующее в конфигурацию Claude:

    "mcpServers": {
        "sketchup": {
            "command": "uvx",
            "args": [
                "sketchup-mcp2"
            ]
        }
    }

Это загрузит последнюю версию с PyPI

После подключения Claude сможет взаимодействовать со Sketchup, используя следующие возможности:

Инструменты

Геометрия и трансформации:

• create_component — Создание куба/цилиндра/конуса/сферы с заданными размерами (мм)

• delete_component — Удаление компонента из сцены

• transform_component — Перемещение/вращение/масштабирование компонента (перемещение в мм)

• set_material — Применение именованных или шестнадцатеричных (#rrggbb) цветов к компоненту

• export_scene — Экспорт в skp/obj/dae/stl/png/jpg

Булевы операции и операции с ребрами:

• boolean_operation — Объединение/вычитание/пересечение двух тел

• chamfer_edge — Снятие фаски со всех ребер группы/компонента (расстояние в мм)

• fillet_edge — Скругление всех ребер (радиус в мм, сегменты настраиваются)

Столярные соединения:

• create_mortise_tenon, create_dovetail, create_finger_joint — Столярные соединения (размеры в мм)

Интроспекция:

• get_model_info — Путь, название, единицы измерения, ограничивающая рамка (bbox) активной модели

• list_components — Дерево групп/компонентов с ограничивающими рамками (рекурсивно, max_depth)

• get_component_info — Подробности об одной сущности по id

• find_components — Поиск по имени/типу/слою

• list_layers, create_layer — Управление слоями/тегами

• get_selection — ID и метаданные текущих выбранных сущностей

• undo — Отмена последней операции

Запасной вариант:

• eval_ruby — Выполнение произвольного кода Ruby в SketchUp для всего, что не покрыто выше

Примеры команд

Вот несколько примеров того, что вы можете попросить Claude сделать:

• "Создай простую модель дома с крышей и окнами"

• "Выбери все компоненты и получи информацию о них"

• "Сделай выбранный компонент красным"

• "Перемести выбранный компонент на 10 единиц вверх"

• "Экспортируй текущую сцену как 3D-модель"

• "Создай сложный шкаф в стиле искусств и ремесел, используя код Ruby"

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

• Проблемы с подключением: Убедитесь, что запущены и сервер расширения Sketchup, и MCP-сервер

• Ошибки команд: Проверьте консоль Ruby (Ruby Console) в Sketchup на наличие сообщений об ошибках

• Ошибки тайм-аута: Попробуйте упростить запросы или разбить их на более мелкие шаги

Технические детали

Протокол связи

Система использует простой протокол на основе JSON поверх TCP-сокетов:

• Команды отправляются как JSON-объекты с полем type и необязательными params

• Ответы — это JSON-объекты с полем status и result или message

Вклад в проект

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request.

Лицензия

MIT

Конфигурация MCP

Добавьте в ваш .mcp.json (Claude Code) или эквивалентную конфигурацию клиента:

{
  "mcpServers": {
    "sketchup": {
      "command": "uvx",
      "args": ["sketchup-mcp2"],
      "env": {
        "SKETCHUP_MCP_HOST": "127.0.0.1",
        "SKETCHUP_MCP_PORT": "9876",
        "SKETCHUP_MCP_TIMEOUT": "60",
        "SKETCHUP_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Ручной запуск (без MCP-клиента):

uvx sketchup-mcp2

Сложные сценарии

Для работы с полными моделями SketchUp (стены, крыши, каркасы, соединения) через eval_ruby см. подробные фрагменты кода Ruby в docs/sketchup-ruby-cookbook.md:

• «Проверка открытой модели» — запрос пути, слоев, ограничивающей рамки.

• «Создание геометрии — надежный помощник make_box» — безопасное выдавливание face.normal.z.

• «Каркасная стена (стойки + обвязки)» — полная секция стены.

• «Стена с проемом» — вырезание отверстий в компланарных гранях.

• «Двускатная / вальмовая крыша» — ручное построение треугольников.

• «follow_me — профиль вдоль пути» — мауэрлат по периметру.

• «Распространенные ошибки» — включая нюанс с обратной семантикой Group#subtract.

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

SketchUp not running or extension not started: ...

Python MCP-сервер попытался подключиться к порту 9876, но не нашел слушающего процесса. Либо:

• SketchUp не запущен, или

• Плагин MCP установлен, но не запущен — откройте Plugins → MCP Server → Start.

Сервер остается активным после этой ошибки; следующий вызов инструмента повторит попытку подключения.