sketchup-mcp2
SketchupMCP - Sketchup 模型上下文协议集成
最初派生自 mhyrr/sketchup-mcp。 从 v0.0.1 版本开始分叉,采用了新的线路协议(4 字节长度前缀帧)、 模块化处理程序架构、扩展的内省/榫卯/边缘操作工具, 并在 Ruby 和 Python 两端实现了完整的单元测试覆盖。 已发布至 PyPI,包名为
sketchup-mcp2(原始sketchup-mcp包为上游)。
SketchupMCP 通过模型上下文协议 (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/):一个模块化的 Ruby 插件,在 SketchUp 内部运行 TCP 服务器 (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 中,转到“窗口” > “扩展程序管理器”
点击“安装扩展程序”并选择下载的
.rbz文件重启 Sketchup
使用方法
启动连接
在 Sketchup 中,转到“扩展程序” > “SketchupMCP” > “启动服务器”
服务器将在默认端口 (9876) 上启动
确保 MCP 服务器正在你的终端中运行
与 Claude 一起使用
通过将以下内容添加到你的 Claude 配置中,配置 Claude 使用 MCP 服务器:
"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— 活动模型的路径、标题、单位、边界框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 — 沿路径的轮廓” — 沿周边的墙板。
“常见陷阱” — 包括
Group#subtract反向语义的坑。
故障排除
SketchUp not running or extension not started: ...
Python MCP 服务器尝试在 9876 端口连接,但发现没有监听。要么:
SketchUp 未运行,或者
MCP 插件已安装但未启动 — 打开“插件” → “MCP Server” → “启动”。
服务器在此错误后保持活动状态;下一次工具调用将重试连接。
Available Tools
20 toolsboolean_operationADestructive
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.
The result is a new group with a new id. With delete_originals=true it takes the target's name, tag and material; otherwise the target stays and the result keeps SketchUp's name (Union, Difference or Intersection). An operand inside a component or group that is placed more than once is refused with -32602.
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.
chamfer_edgeADestructive
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. The body comes back as a new group with a new id and keeps its name, tag and material. A body inside a component or group that is placed more than once is refused with -32602.
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.
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), in world (model) coordinates; 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.
When the user has a group or component open for editing in SketchUp, the new object goes inside it, as with SketchUp's own tools (get_model_info.editing shows the open path). If that group or component, or one holding it, is placed more than once in the model, the call is refused with -32602: the object would appear in every copy.
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.
create_layerBIdempotent
Create a new layer (tag) with the given name.
Returns: JSON {id, name, visible}.
Inputs: name (required).
create_mortise_tenonADestructive
Create a mortise-and-tenon joint between two boards that touch face to face.
All dimensions in millimeters. The boards must be solid groups or component instances in the same parent and touch along one face: no gap and no overlap. Each board's rotation in the model — its own and that of any group or component holding it — must be a multiple of 90°: the joint follows the model's X, Y and Z axes, the same axes bbox_mm uses, whether or not a group is open for editing. A board that is itself open for editing is refused (close it first), and so are boards inside a component or group that is placed more than once. The joint is centred on the area where they touch; offsets move it along the two axes across the joint (the offset along the joint axis is ignored). width runs along the first cross axis and height along the second: for a joint along X, width is along Y and height along Z; along Y, width along X and height along Z; along Z, width along X and height along Y. depth is how far the tenon reaches into the mortise board; a depth beyond its thickness makes a through mortise, and the tenon then sticks out past the mortise board's far face by depth minus the thickness. The joint must fit inside the contact area and may reach its edge. A depth equal to the mortise board's thickness, or a joint that reaches the edge of the contact area, puts a face of the cut in a face of the board, which SketchUp's solid operations can fail on (-32603): avoid both when possible. The mortise board must fill its bounding box where the boards touch, and the pocket must not meet an earlier one (its tenon would run into the earlier tenon); otherwise the joint is refused (-32603) with advice: a shallower joint, or the offsets. Defaults are sized for ~100 mm boards.
The mortise is cut into the mortise board and the tenon is joined to the tenon board as one solid. Both boards come back as new groups with new ids and keep their names, tags and the group's own material; the faces the joint adds (the pocket's walls and the tenon) carry no material of their own. A joint that cannot be built is refused: -32602 for boards that do not suit, -32603 when SketchUp's solid operations fail. Nothing is half-built.
Returns: JSON {mortise: {id, name, type, bbox_mm|null}, tenon: {...}}.
Inputs: tenon_id (required), mortise_id (required), depth, width, +4 more.
delete_componentADestructiveIdempotent
Delete a group or component instance by entity ID. Raw faces, edges and other entities fail with -32602.
An entity inside a component or group that is placed more than once is refused with -32602: deleting it would delete it from every copy. A top-level copy itself can be deleted.
Returns: JSON {ok: true}.
Inputs: id (required).
eval_rubyADestructive
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 tool returns that message as an error result, verbatim — without
the [code] prefix that other errors carry — so the LLM can repeat it
to the user.
Code works in inches (SketchUp's internal unit), not mm, and opens no undo operation of its own: wrap edits in model.start_operation(...) / model.commit_operation to make them one undo step. Its def and constant definitions become global in SketchUp's Ruby session and stay there.
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. Other errors come back
as error results with the text "[code] message", carrying the Ruby
exception class and message.
Inputs: code (required).
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.
fillet_edgeADestructive
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. The body comes back as a new group with a new id and keeps its name, tag and material. A body inside a component or group that is placed more than once is refused with -32602.
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.
find_componentsARead-onlyIdempotent
Find components matching name substring, layer, and/or type.
Name matching is a case-insensitive substring of the instance name or, for component instances, the definition name — the name the Outliner shows for components from the 3D Warehouse or an import; layer must match exactly. Searches recursively (bounded by max_depth). With no filters it returns all components up to max_depth (paginated) — same traversal and rows as list_components: world-coordinate bounds, shared, definition.
Returns: JSON {components[], total, offset, truncated} — if truncated, request the next page with offset += limit.
Inputs: name, type, layer, limit, +3 more.
get_component_infoARead-onlyIdempotent
Detailed info for a single group or component instance by entity ID.
bbox_mm is in world coordinates, worked out through the entity's parents, whether or not a group is open for editing. For an entity inside a component or group placed more than once, shared is true and bbox_mm is that of the copy open for editing when there is one, else of the first placed copy (list_components lists every copy).
Returns: JSON {id, name, type, layer, depth, shared, definition (components only), bbox_mm|null}.
Inputs: id (required).
get_model_infoARead-onlyIdempotent
Get current SketchUp model info: file path, title, units, bounding box, entity count, layer list, open edit path.
entity_count counts top-level entities only. editing lists the groups and components open for editing in SketchUp, outermost first, as [{id, name, shared}]; create_component puts new objects into the last one. shared is true when the contents of that group or component are shared — it, or one holding it, is placed more than once — so the entities inside it are listed with shared: true as well, and create_component refuses while the last one is shared: the new object would appear in every copy.
Returns: JSON {path, title, units: "mm", bounding_box_mm|null, entity_count, layers[], editing[]}.
Inputs: no named parameters.
get_selectionARead-onlyIdempotent
Get the entities currently selected in the SketchUp UI.
Returns: JSON {entities: [...]} — groups/components are {id, name, type, layer, depth, shared, definition (components only), bbox_mm|null}, as get_component_info reports them, with bbox_mm in world coordinates; other selected entities (edges, faces, ...) are {id, type} only.
Inputs: no named parameters.
get_versionARead-onlyIdempotent
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.
get_viewport_screenshotARead-onlyIdempotent
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..2000). 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. Errors come back as error results with the text "[code] message", as for every tool.
Inputs: style, max_size, view_preset, restore_view, +1 more.
list_componentsARead-onlyIdempotent
List groups and component instances in the model (paginated).
Each component is {id, name, type, layer, depth, shared, definition, bbox_mm} (detailed) or the same without bbox_mm (concise); bounds are world-coordinate mm. shared is true for an entity inside a component or group placed more than once: typed edits to it are refused. definition, on component rows only, is the component's definition name. Set recursive=true to descend into nested components (bounded by max_depth, default 3); a component placed several times lists its contents once per placement.
Returns: JSON {components[], total, offset, truncated} — if truncated, request the next page with offset += limit.
Inputs: limit, offset, max_depth, recursive, +1 more.
list_layersARead-onlyIdempotent
List all model layers (tags).
Returns: JSON {layers: [{name, visible, color, id}]}.
Inputs: no named parameters.
set_materialADestructiveIdempotent
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). A face or edge (an id from get_selection) is painted where it is; one inside a component or group that is placed more than once is refused with -32602, since every copy would change.
Returns: JSON {id, name, type, bbox_mm{min,max}|null}, bbox_mm in world coordinates. For a face or edge, type is "face" or "edge" and name is null.
Inputs: id (required), material (required).
transform_componentADestructive
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 world (model) coordinates, in mm — the same anchor create_component uses and the same frame bbox_mm reports, for nested entities too. 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 about the world X, then Y, then Z axis, through the center of the world bbox.
scale: RELATIVE scale factors along the world axes, about the center of the world bbox.
An entity inside a component or group that is placed more than once is refused with -32602: moving it would move it in every copy.
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.
undoADestructive
Undo the last step of SketchUp's shared undo stack.
One MCP tool-call is one undo step, but the stack is shared with the user: the last step may be the user's own edit rather than the last MCP call. undo answers before SketchUp has processed it, so check the model afterwards (get_component_info / list_components).
Returns: JSON {ok: true}.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools have clearly distinct resource/action pairs, but list_components and find_components overlap significantly: find with no filters returns the same rows and traversal as list. eval_ruby is also a broad escape hatch that conceptually overlaps with all typed editing tools, though the descriptions help clarify intended use.
The naming is predominantly consistent snake_case with a verb_noun pattern (create_component, get_model_info, list_layers, transform_component). Minor deviations exist, notably boolean_operation as a noun phrase and undo lacking a noun, but the overall convention is still readable and predictable.
At 20 tools this is at the high end for the ideal 3–15 range, but the domain is genuinely broad: primitive creation, editing, inspection, export, layers, undo, screenshots, and debugging. Each tool appears to cover a distinct operation, so the set is slightly over-scoped but not bloated.
Coverage is strong across modeling operations: create/delete/transform components, primitives, booleans, chamfer/fillet, materials, layers, inspection, export, screenshots, undo, and eval_ruby. Minor gaps remain, such as layer update/delete, material listing, and component duplication, but these are workable via eval_ruby or existing tools.
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.
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
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.
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.2120 PyPI7MIT