Skip to main content
Glama
sketchup-mcp2

sketchup-mcp2

by zinin

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를 여세요.

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

Available Tools

22 tools
boolean_operationA

Perform a boolean operation (union / difference / intersection) on two solids.

difference = target minus tool. Operating on an instance of a shared definition consumes only that instance — the result is a new group, sibling instances are untouched. Unreliable on non-manifold geometry.

Returns: JSON {id, name, type, bbox_mm{min,max}|null}. Read bbox_mm to verify the result; it is null for empty geometry (e.g. a difference that consumed the whole body).

Inputs: tool_id (required), target_id (required), operation, delete_originals. Returns: result

chamfer_edgeA

Chamfer (bevel) every feature edge of a group/component by distance mm.

Seams of curved surfaces — edges where the surface bends by less than 25° (the two face normals differ by under 25°), such as a cylinder's vertical facet edges or every edge of a sphere — are skipped; the rims of curved surfaces are chamfered segment by segment. Concave (inside-corner) edges, such as the base of a post or the inner corner of an L-shaped block, are skipped too: chamfering them would need added material. A body with no feature edges fails with -32602, as does an inside-out body (faces pointing inward): reverse its faces first. A call starts no new cut after 30 s inside SketchUp and then rolls back, changing nothing. Unreliable on non-manifold geometry.

Returns: JSON {id, name, type, bbox_mm|null, edges_chamfered, stats{attempted, succeeded, subtract_failed, skipped_no_match, skipped_seam, skipped_concave, skipped_curved}} — check stats.subtract_failed == 0 (failed cuts) and stats.skipped_no_match == 0 (edges consumed by earlier cuts).

Inputs: id (required), distance. Returns: result

create_componentA

Create a primitive (cube / cylinder / cone / sphere) in SketchUp.

All linear values are millimeters (mm). Minimum size per dimension: 0.1 mm for cube (thin stock like veneer is fine), 1.0 mm for sphere / cylinder / cone (tessellated types degenerate earlier). position is the bounding-box MIN corner (not the center); the same anchor is used by transform_component.position. Per-type dimensions: cube uses [x, y, z]; cylinder and cone use [0]=diameter, [2]=height ([1] is ignored); sphere uses [0]=diameter only. New geometry is wrapped in a SketchUp Group.

Returns: JSON {id, name, type, bbox_mm{min,max}|null}. Read bbox_mm to verify the result before the next step.

Inputs: name, type, position, dimensions. Returns: result

create_dovetailA

Create a dovetail joint between two boards.

All dimensions in millimeters; angle is in degrees, valid range (0, 60]. Offsets shift the joint from the board face's center. Defaults are sized for ~100 mm boards. The two boards must already touch/overlap along the joint axis.

Returns: JSON {tail: {id, name, type, bbox_mm|null}, pin: {...}, boolean_cuts: {attempted, failed}} — non-zero failed means some cuts did not apply (likely non-manifold geometry); verify via bbox_mm.

Inputs: pin_id (required), tail_id (required), angle, depth, +6 more. Returns: result

create_finger_jointA

Create a finger joint (box joint) between two boards.

All dimensions in millimeters; offsets shift the joint from the board face's center. Defaults are sized for ~100 mm boards. The two boards must already touch/overlap along the joint axis.

Returns: JSON {board1: {id, name, type, bbox_mm|null}, board2: {...}, boolean_cuts: {attempted, failed}} — non-zero failed means some cuts did not apply (likely non-manifold geometry); verify via bbox_mm.

Inputs: board1_id (required), board2_id (required), depth, width, +5 more. Returns: result

create_layerA

Create a new layer (tag) with the given name.

Returns: JSON {id, name, visible}.

Inputs: name (required). Returns: result

create_mortise_tenonA

Create a mortise-and-tenon joint between two boards.

All dimensions in millimeters; offsets shift the joint from the board face's center. Defaults are sized for ~100 mm boards. The two boards must already touch/overlap along the joint axis.

Returns: JSON {mortise: {id, name, type, bbox_mm|null}, tenon: {...}, boolean_cuts: {attempted, failed}} — non-zero failed means some cuts did not apply (likely non-manifold geometry); verify via bbox_mm.

Inputs: tenon_id (required), mortise_id (required), depth, width, +4 more. Returns: result

delete_componentA

Delete a group or component instance by entity ID. Raw faces, edges and other entities fail with -32602.

Returns: JSON {ok: true}.

Inputs: id (required). Returns: result

eval_rubyA

Evaluate arbitrary Ruby code in SketchUp.

Enabled by default; the user can close the gate in the SketchUp extension's Settings. When closed, the SketchUp side returns JSON-RPC code -32010 with a user-facing message explaining how to re-enable it. This wrapper surfaces that message as a plain string so the LLM can repeat it to the user verbatim — without the [code] prefix that format_error would otherwise add.

Returns the .to_s of the LAST evaluated expression; stdout (puts) is NOT captured. End scripts with an explicit expression — e.g. a final result.to_json — to get structured data back. Errors return "[code] message" with the Ruby exception class and message.

Inputs: code (required). Returns: result

export_sceneA

Export the current scene to a temp file on the SketchUp host.

Formats: skp (native), obj / dae / stl (geometry), png / jpg (viewport render, default 1920×1080). The file is written on the machine running SketchUp — on a split-host setup the path is not directly readable here. An untitled model cannot be exported to skp (-32602) — the user must save it first; other formats work.

Returns: JSON {path, format}.

Inputs: format. Returns: result

fillet_edgeA

Round (fillet) every straight feature edge of a group/component by radius mm with segments arc segments.

Skips seams of curved surfaces (edges where the surface bends by less than 25°: the two face normals differ by under 25°) and the rims of curved surfaces, such as a cylinder's top and bottom circles: fillet cannot round a tessellated curve. Also skips concave (inside-corner) edges, such as the base of a post or the inner corner of an L-shaped block: rounding them would need added material. A body with no straight feature edges (cylinder, cone, sphere) fails with -32602, as does an inside-out body (faces pointing inward): reverse its faces first. A call starts no new cut after 30 s inside SketchUp and then rolls back, changing nothing. Unreliable on non-manifold geometry.

Returns: JSON {id, name, type, bbox_mm|null, edges_filleted, stats{attempted, succeeded, subtract_failed, skipped_no_match, skipped_seam, skipped_concave, skipped_curved}} — check stats.subtract_failed == 0 (failed cuts) and stats.skipped_no_match == 0 (edges consumed by earlier cuts).

Inputs: id (required), radius, segments. Returns: result

find_componentsA

Find components matching name substring, layer, and/or type.

Name matching is case-insensitive substring; layer must match exactly. Searches recursively (bounded by max_depth). With no filters it returns all components up to max_depth (paginated) — same traversal as list_components.

Returns: JSON {components[], total, offset, truncated} — if truncated, request the next page with offset += limit.

Inputs: name, type, layer, limit, +3 more. Returns: result

get_component_infoA

Detailed info for a single group or component instance by entity ID.

Returns: JSON {id, name, type, layer, depth, bbox_mm|null}.

Inputs: id (required). Returns: result

get_model_infoA

Get current SketchUp model info: file path, title, units, bounding box, entity count, layer list.

Returns: JSON {path, title, units: "mm", bounding_box_mm|null, entity_count, layers[]}.

Inputs: no named parameters. Returns: result

get_selectionA

Get the entities currently selected in the SketchUp UI.

Returns: JSON {entities: [...]} — groups/components are {id, name, type, layer, depth, bbox_mm|null}; other selected entities (edges, faces, ...) are {id, type} only.

Inputs: no named parameters. Returns: result

get_versionA

Return the server version and Python↔Ruby compatibility verdict.

Useful as a runtime sanity probe — always returns a payload, even when the connection or other tools surface errors. The result is a JSON string with fields: python_version, ruby_version, min_compatible_ruby, ruby_min_compatible_python, compatible (bool), error (string | null).

Inputs: no named parameters. Returns: result

get_viewport_screenshotA

Capture the current SketchUp viewport; returns the PNG image plus a JSON text block {width, height, preset_used, style_used}.

Useful for letting Claude visually verify the scene between steps.

Parameters

  • max_size: largest side of the returned PNG (64..4096). Aspect ratio is taken from the current viewport; the smaller side is scaled proportionally.

  • view_preset: switch the camera to a standard view before snapping. current leaves the camera alone.

  • zoom_extents: call view.zoom_extents before snapping.

  • style: temporarily flip a small set of rendering_options keys. default leaves them alone.

  • restore_view: when true (default), camera and rendering_options are snapshotted before mutation and restored after the snapshot, so the user's viewport is unchanged.

If the connection drops mid-response the call is retried automatically; the viewport may briefly flicker in that rare case.

Inputs: style, max_size, view_preset, restore_view, +1 more.

list_componentsA

List groups and component instances in the model (paginated).

Each component is {id, name, type, layer, depth, bbox_mm} (detailed) or {id, name, type, layer, depth} (concise); bounds are world-coordinate mm. Set recursive=true to descend into nested components (bounded by max_depth, default 3).

Returns: JSON {components[], total, offset, truncated} — if truncated, request the next page with offset += limit.

Inputs: limit, offset, max_depth, recursive, +1 more. Returns: result

list_layersA

List all model layers (tags).

Returns: JSON {layers: [{name, visible, color, id}]}.

Inputs: no named parameters. Returns: result

set_materialA

Assign a material (color) to a group, component instance, face or edge.

material: a material already in the model, matched by name without regard to case, is used as is (so an existing "Red" is used for "red"). Otherwise a named color — red, green, blue, yellow, cyan, turquoise, magenta, purple, white, black, brown, wood, orange, gray, grey — or a 6-digit hex string like "#a05030" (#rrggbb), in any case, maps to one lower-case material, found or created. Anything else fails with -32602. Painting a group/component affects only this instance (it is made unique first); painting a raw face/edge id (obtainable via get_selection) colors the shared definition — all instances show it.

Returns: JSON {id, name, type, bbox_mm{min,max}|null}. For a face or edge, type is "face" or "edge" and name is null.

Inputs: id (required), material (required). Returns: result

transform_componentA

Move, rotate and/or scale a group or component (mm / degrees).

Groups and component instances only; other entities fail with -32602.

  • position: ABSOLUTE target for the entity's bounding-box MIN corner, in mm — the same anchor create_component uses. Applied LAST (after rotation/scale), so the final bbox-min lands exactly at [x, y, z] even in combined calls. It is NOT a relative offset: repeating the same position is idempotent.

  • rotation: RELATIVE rotation in degrees around the bbox center, applied sequentially about world X, then Y, then Z.

  • scale: RELATIVE scale factors about the bbox center.

These validations (3-element lists, non-zero scale) apply only to this typed tool — raw Ruby driven through eval_ruby bypasses them.

Returns: JSON {id, name, type, bbox_mm{min,max}|null}. Read bbox_mm to verify the result; it is null for empty geometry.

Inputs: id (required), scale, position, rotation. Returns: result

undoA

Undo the last atomic operation in SketchUp. One MCP tool-call = one undo step.

Returns: JSON {ok: true}.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 22 tools

    Disambiguation4/5

    Each tool targets a clear resource+action (create primitive, transform, boolean, joints, chamfer/fillet, query, export, screenshot). The only real overlap is list_components vs find_components, since find_components with no filters reproduces the same traversal as list_components; descriptions distinguish them but an agent could still pick the wrong one.

    Naming Consistency4/5

    Strong verb_noun snake_case pattern throughout (create_component, transform_component, get_model_info, list_layers, chamfer_edge, create_dovetail, etc.). Minor deviations: the bare 'undo' and the noun-style 'boolean_operation' break the pattern slightly, but the convention is otherwise predictable.

    Tool Count4/5

    22 tools is on the heavier side, but the domain is broad (primitive creation, joinery, mesh ops, queries, export, viewport, Ruby escape hatch) and nearly every tool earns a distinct slot. It stays within a reasonable envelope rather than sprawling into redundant duplicates.

    Completeness4/5

    Covers the full lifecycle: create (primitive/joint/layer), transform, material, boolean, chamfer/fillet, delete, list/find/info, export, screenshot, undo. Gaps are minor — no layer delete/rename or material removal — and eval_ruby provides an escape hatch for anything missing.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Connects Sketchup to Claude AI through the Model Context Protocol, allowing Claude to directly interact with and control Sketchup for prompt-assisted 3D modeling and scene manipulation.
      10
      557
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables direct interaction and control of SketchUp through Claude AI using the Model Context Protocol and a TCP socket connection. It allows for prompt-assisted 3D modeling, component manipulation, and the execution of arbitrary Ruby code within the SketchUp environment.
      10
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Connects Claude AI to SketchUp, allowing you to create and modify 3D models via natural language commands.
      21
      7
      MIT