sketchup-mcp2
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
구성 요소
이 시스템은 두 가지 주요 구성 요소로 이루어져 있습니다:
SketchUp 확장 프로그램 (
su_mcp/su_mcp/): SketchUp 내에서 TCP 서버를 실행하는 모듈식 Ruby 플러그인 (core/,handlers/,helpers/).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 확장 프로그램
최신
.rbz파일을 다운로드하거나 빌드합니다.Sketchup에서 Window > Extension Manager로 이동합니다.
"Install Extension"을 클릭하고 다운로드한
.rbz파일을 선택합니다.Sketchup을 다시 시작합니다.
사용법
연결 시작
Sketchup에서 Extensions > SketchupMCP > Start Server로 이동합니다.
서버가 기본 포트(9876)에서 시작됩니다.
터미널에서 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 toolsboolean_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.
currentleaves the camera alone.zoom_extents: call view.zoom_extents before snapping.
style: temporarily flip a small set of rendering_options keys.
defaultleaves 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
Scored across 22 tools
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.
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.
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.
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
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Related MCP Servers
- AlicenseBqualityDmaintenanceConnects 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.10557MIT
- AlicenseBqualityDmaintenanceIntegration that connects Sketchup to Claude AI through the Model Context Protocol, allowing Claude to directly interact with and control Sketchup for prompt-assisted 3D modeling, scene creation, and manipulation.1028MIT
- AlicenseBqualityDmaintenanceEnables 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.101MIT
- AlicenseAqualityDmaintenanceConnects Claude AI to SketchUp, allowing you to create and modify 3D models via natural language commands.217MIT