SketchupMCP - Sketchup Model Context Protocol 통합

원래 mhyrr/sketchup-mcp에서 포크되었습니다. v0.0.1에서 새로운 와이어 프로토콜(4바이트 길이 접두사 프레이밍), 모듈식 핸들러 아키텍처, 확장된 인트로스펙션 / 결합 / 엣지 작업 도구, 그리고 Ruby와 Python 양쪽 모두에 대한 전체 단위 테스트 커버리지로 분기되었습니다. sketchup-mcp2로 PyPI에 게시되었습니다(원래 sketchup-mcp 패키지는 업스트림입니다).

SketchupMCP는 Model Context Protocol(MCP)을 통해 Sketchup을 Claude AI에 연결하여 Claude가 Sketchup과 직접 상호 작용하고 제어할 수 있도록 합니다. 이 통합을 통해 Sketchup에서 프롬프트 기반 3D 모델링, 장면 생성 및 조작이 가능합니다.

영감과 구조를 제공해 준 Blender MCP에 큰 감사를 표합니다.

기능

• 양방향 통신: TCP 소켓 연결을 통해 Claude AI를 Sketchup에 연결

• 컴포넌트 조작: Sketchup에서 컴포넌트 생성, 수정, 삭제 및 변환

• 재질 제어: 재질 및 색상 적용 및 수정

• 장면 검사: 현재 Sketchup 장면에 대한 상세 정보 획득

• 선택 처리: 선택된 컴포넌트 가져오기 및 조작

• Ruby 코드 평가: 고급 작업을 위해 SketchUp에서 임의의 Ruby 코드를 직접 실행

Related MCP server: SketchupMCP

구성 요소

이 시스템은 두 가지 주요 구성 요소로 이루어져 있습니다:

1. SketchUp 확장 프로그램 (su_mcp/su_mcp/): SketchUp 내에서 TCP 서버를 실행하는 모듈식 Ruby 플러그인 (core/, handlers/, helpers/).

2. MCP 서버 (src/sketchup_mcp/): FastMCP 기반으로 구축된 모듈식 Python 패키지 — tools.py는 MCP 도구를 노출하고, connection.py는 4바이트 길이 접두사 프레이밍이 있는 지속적 TCP 소켓을 소유하며, 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 구성에 다음을 추가하여 Claude가 MCP 서버를 사용하도록 설정합니다:

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

이것은 PyPI의 최신 버전을 가져옵니다.

연결되면 Claude는 다음 기능을 사용하여 Sketchup과 상호 작용할 수 있습니다:

도구

지오메트리 및 변환:

• create_component — 지정된 치수(mm)로 큐브/실린더/원뿔/구 생성

• delete_component — 장면에서 컴포넌트 제거

• transform_component — 컴포넌트 이동/회전/크기 조절(이동은 mm 단위)

• set_material — 컴포넌트에 이름 또는 16진수(#rrggbb) 색상 적용

• export_scene — skp/obj/dae/stl/png/jpg로 내보내기

불리언 및 엣지 작업:

• boolean_operation — 두 솔리드 간의 합집합/차집합/교집합

• chamfer_edge — 그룹/컴포넌트의 모든 엣지 모따기(거리 mm 단위)

• fillet_edge — 모든 엣지 필렛(둥글게 처리)(반경 mm 단위, 세그먼트 구성 가능)

결합(Joinery):

• create_mortise_tenon, create_dovetail, create_finger_joint — 목공 결합(치수 mm 단위)

인트로스펙션:

• get_model_info — 활성 모델의 경로, 제목, 단위, 경계 상자(bbox)

• list_components — 경계 상자가 포함된 그룹/컴포넌트 트리(재귀적, max_depth)

• get_component_info — ID별 엔티티 상세 정보

• find_components — 이름/유형/레이어별 검색

• list_layers, create_layer — 레이어/태그 관리

• get_selection — 현재 선택된 엔티티의 ID 및 메타데이터

• undo — 마지막 작업 되돌리기

탈출구:

• eval_ruby — 위에서 다루지 않은 모든 작업을 위해 SketchUp에서 임의의 Ruby 코드 실행

예제 명령어

Claude에게 요청할 수 있는 몇 가지 예시는 다음과 같습니다:

• "지붕과 창문이 있는 간단한 집 모델을 만들어줘"

• "모든 컴포넌트를 선택하고 정보를 가져와줘"

• "선택한 컴포넌트를 빨간색으로 만들어줘"

• "선택한 컴포넌트를 위로 10단위 이동해줘"

• "현재 장면을 3D 모델로 내보내줘"

• "Ruby 코드를 사용하여 복잡한 예술 및 공예 캐비닛을 만들어줘"

문제 해결

• 연결 문제: Sketchup 확장 프로그램 서버와 MCP 서버가 모두 실행 중인지 확인하세요.

• 명령 실패: Sketchup의 Ruby 콘솔에서 오류 메시지를 확인하세요.

• 시간 초과 오류: 요청을 단순화하거나 더 작은 단계로 나누어 보세요.

기술 세부 정보

통신 프로토콜

이 시스템은 TCP 소켓을 통해 간단한 JSON 기반 프로토콜을 사용합니다:

• 명령은 type과 선택적 params가 포함된 JSON 객체로 전송됩니다.

• 응답은 status와 result 또는 message가 포함된 JSON 객체입니다.

기여

기여를 환영합니다! 자유롭게 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

복잡한 시나리오

eval_ruby를 통해 전체 SketchUp 모델(벽, 지붕, 프레임, 결합)을 작업하려면 docs/sketchup-ruby-cookbook.md의 상세 Ruby 스니펫을 참조하세요:

• «열린 모델 검사» — 경로, 레이어, 경계 상자 쿼리.

• «지오메트리 생성 — 신뢰할 수 있는 make_box 도우미» — face.normal.z 안전 돌출.

• «프레임 벽(스터드 + 플레이트)» — 전체 벽 섹션.

• «개구부가 있는 벽» — 동일 평면 면 구멍 뚫기.

• «박공 / 힙 지붕» — 수동 삼각형 구성.

• «follow_me — 경로를 따라 프로필» — 둘레를 따라 mauerlat.

• «일반적인 함정» — Group#subtract의 반전된 의미론적 함정 포함.

문제 해결

SketchUp not running or extension not started: ...

Python MCP 서버가 포트 9876에서 연결을 시도했지만 수신 대기 중인 항목을 찾지 못했습니다. 다음 중 하나를 확인하세요:

• SketchUp이 실행 중이지 않거나,

• MCP 플러그인이 설치되었지만 시작되지 않았습니다 — Plugins → MCP Server → Start를 여세요.

이 오류 후에도 서버는 계속 유지됩니다. 다음 도구 호출 시 연결을 다시 시도합니다.