sketchup-mcp
Provides tools for reading and modifying the currently open SketchUp 2023 model: querying model info, units, components, materials, tags, selection and quantities, as well as creating geometry, copying/moving/rotating/scaling objects, applying materials, staging modeling steps, undoing, setting views, taking screenshots, exporting, and running Ruby API code.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sketchup-mcp read the current SketchUp model's path, units, and components"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SketchUp Codex Bridge
通过 Codex 的自然语言指令,读取和修改本机当前打开的 SketchUp 模型。
这是面向 Windows + SketchUp 2023 + Codex 的可复用部署包,基于 2ez4gcx/sketchup-mcp 的 v1.2.0。上游 MCP 服务、Ruby 桥接及许可证保留原样;本仓库提供中文部署、保护原配置的注册脚本、只读诊断、测试示例和自动检查。
不包含任何住宅施工图、客户模型、现场照片、效果图、账号配置或密钥。它是本地桌面控制工具,不是部署在 GitHub Pages 上的远程建模服务。
flowchart LR
A[Codex] -->|本地 stdio / MCP| B[Node.js MCP 服务]
B -->|127.0.0.1:9876| C[SketchUp SU MCP Bridge]
C --> D[Ruby API / 当前模型]能做什么
读取模型、单位、组件、材质、标签、选中内容及工程量。
创建几何、复制移动旋转缩放、贴材质、分阶段建模和撤销。
设置视角、截图、导出及运行 Ruby API 代码。
配合客户端的生图工具生成效果图;桥接本身不提供GPT生图或照片级渲染。
Related MCP server: SketchupMCP
环境
Windows、可正常运行并加载扩展的 SketchUp 2023。
Node.js 18 或以上;Codex 桌面端或 CLI。
SketchUp 与 Codex 必须运行在同一台电脑。GitHub Actions 仅测试部署包,不运行 SketchUp。
上游声明测试过 Windows SketchUp 2021/2023;本部署方案在2026-10-20的本机 SketchUp 2023 环境完成过建模操作验证。其他版本不据此宣称已验证。
仓库已包含固定版本的官方程序文件,无需 npm install,不执行下载后直接运行的远程安装脚本。
快速开始
1. 下载并检查
git clone https://github.com/wc970321-collab/sketchup-codex-bridge.git
cd sketchup-codex-bridge
node --version
node scripts/verify-vendor.mjs
npm test从 GitHub 下载 ZIP 也可以,先解压到长期保留的目录。路径可以包含中文和空格;注册后不要移动目录,否则需手动更新 Codex 中的路径。
2. 安装 SketchUp 桥接
在 SketchUp 2023 的「扩展程序 → 扩展程序管理器 → 安装扩展」选择:
vendor/sketchup-mcp-1.2.0/bridge/su_mcp.rbz完全退出并重新打开 SketchUp,查看「扩展程序 → SU MCP Bridge → Status」,应显示 RUNNING on 127.0.0.1:9876。
不覆盖 SketchUp 安装目录,不要求在 Program Files 中写入。若未签名插件受到组织策略限制,请通过正常扩展管理流程处理,不绕过策略。
3. 注册 Codex
建议先注册只读工具,验证目标模型:
node scripts/configure-codex.mjs需要直接建模时,在尚未注册本服务的新环境可改用:
node scripts/configure-codex.mjs --enable-write注册脚本使用当前 Node 与仓库的绝对路径,目标为 CODEX_HOME/config.toml,未设置时为用户目录下 .codex/config.toml。有原配置会先备份并保留原字节;检测到已有 sketchup 项就停止,不替换、不自动迁移当前环境。
已经注册只读、现在需要写操作:手动删除 [mcp_servers.sketchup] 下的 enabled_tools 白名单这一行,保留 default_tools_approval_mode = "prompt",重载 Codex。可用下列命令预览完整配置,不修改文件:
node scripts/configure-codex.mjs --enable-write --print全量写工具包括 run_ruby;只对信任的请求开放。提示行为还受客户端版本和管理策略影响,并非操作系统沙箱。配置字段依据 OpenAI 官方 MCP 文档。
4. 重载并验证
重启或重新加载 Codex 后,先测试:
npm run tools
npm run health
node scripts/mcp-client.mjs model_infotools 列出26项上游工具,不需要 SketchUp;health 与 model_info 需要桥接已启动。模型信息可能包含私人文件名,不要直接公开终端输出。
在 Codex 中说:
使用 SketchUp MCP,读取当前模型路径、单位和组件信息,暂不修改。
确认是目标工作副本后,再请求逐阶段建模。更多用法见 自然语言示例。
验证与文件保护
examples/test-box.rb 只允许在未保存、实体为空、未进入组件编辑的测试模型执行,创建并核验1200×600×900mm盒体组件,不保存或关闭模型。它是连接/尺寸示例,不是施工柜体设计。
每次新会话先读 model_info,重新获取实体ID;先另存副本再修改。一次处理一个小阶段:建实体 → 刷新视图 → 核验尺寸 → 保存到新路径。Undo只针对模型事务,不能撤销外部文件、联网或进程行为。
文件结构
文件 | 用途 |
| 官方固定版本服务与RBZ,原样保留 |
| 官方下载地址、包哈希与逐文件哈希 |
| 备份并追加Codex配置,已有服务时拒绝覆盖 |
| 本地诊断客户端,命令行写操作需显式 |
| 校验上游文件未被修改 |
| Ruby测试示例与中文提示词 |
| 配置保护、MCP握手及上游完整性测试 |
排障
现象 | 处理 |
工具列表成功,ping失败 | 打开目标SketchUp,检查桥接Status或Start server |
控制了另一个窗口 | 多个窗口争用同一端口;停止非目标窗口桥接,再启动目标窗口,勿丢弃未保存工作 |
Codex没有新工具 | 核对绝对路径,完全退出并重启Codex;插件内注册与手动配置不要重复启用 |
只读模式不能建模 | 按第3步手动启用写工具;不要重跑脚本覆盖既有配置 |
端口改过 | 同步修改SketchUp桥接与Codex环境变量;诊断CLI用 |
写操作超时 | 等待SketchUp空闲后先检查状态,勿立即重复执行,否则可能生成重复几何 |
Codex自身执行宿主缺失 | 与MCP桥接分开排查;不要把不同版本EXE混拷到缓存目录,不设置固定哈希目录的 |
安全与开源来源
先阅读 SECURITY.md。桥接只绑定本机回环地址,但无身份认证;任意 Ruby 以当前用户权限执行,不在文件系统沙箱中。使用后可从SketchUp菜单停止桥接;重开SketchUp可能自动启动。
上游 v1.2.0 Release 的 MCPB SHA-256:
be6864a1f18bea06655be40e8a259f24a2457ba6c1300c13ed287dd11f6df2342026-10-21发布整理时,已从官方地址重新下载校验,并将本仓库8个上游文件与包内逐字节比对。升级时服务和RBZ需成套更新,重做哈希校验与兼容验证,不自动追踪最新版。
本仓库的部署胶水和文档采用MIT。原作者 Khuong Doan 的版权与MIT许可证保留在vendor目录;内嵌依赖许可证见 server/THIRD_PARTY_NOTICES.txt。本仓库不是OpenAI或SketchUp官方产品,也未声称重写了上游桥接。
Available Tools
26 toolscreate_boxA
Create a rectangular box (group). width along X, depth along Y, height along Z, in mm. origin [x,y,z] mm is the lower-left corner. Missing tags/materials are created; color is '#RRGGBB' or a color name (only applied when the material is newly created; an existing material keeps its color). Returns: {id, persistent_id, type, name, tag, material, bounds_mm{min,max,size}}.
Inputs: depth (required), width (required), height (required), tag, +4 more.
create_linesA
Draw a polyline through [x,y,z] mm points in a new group. close_face=true: closes back to the first point and creates a face (the result has face_created).
Inputs: points (required), tag, name, close_face.
create_shapeA
Draw a flat face from a polygon (list of [x,y,z] mm points, >= 3 coplanar points) in a new group. pushpull (mm) extrudes it into a solid (e.g. draw a floor outline, then pull it up to the slab thickness). Returns: {id, persistent_id, type, name, tag, material, bounds_mm{min,max,size}}.
Inputs: points (required), tag, name, color, +2 more.
delete_entitiesADestructive
Delete entities by id (ids are required; never deletes by selection). Can be undone.
Inputs: entity_ids (required).
export_fileADestructive
Export the model to a 3D/2D file chosen by extension (dae, obj, stl, fbx, dwg, dxf, 3ds...). Some formats require SketchUp Pro.
Inputs: path (required).
export_pngADestructive
Export the viewport as a PNG/JPG file (e.g. 'D:/Export/perspective.png'). width/height in pixels; view changes the camera first.
Inputs: path (required), view, width, height, +1 more.
insert_componentB
Insert a component: from a .skp file (path, e.g. 'D:/Library/table.skp') or from a definition already in the model (definition = name). position [x,y,z] mm, rotation_deg rotates about the Z axis.
Inputs: tag, name, path, material, +3 more.
install_sketchup_bridgeAIdempotent
Install (or update) the "SU MCP Bridge" extension in SketchUp so the other tools can connect. Copies su_mcp.rb + su_mcp/main.rb into the Plugins folder of every SketchUp version found (Windows: %APPDATA%/SketchUp/SketchUp 20xx/SketchUp/Plugins). SketchUp must be restarted afterwards. Empty versions = every version opened at least once; dry_run=true only reports what would be done. Also returns the path of su_mcp.rbz for a manual install via Extension Manager.
Inputs: dry_run, versions.
list_componentsARead-only
List component definitions and their instance counts (sorted descending) - use it to count equipment/furniture. include_groups=true also lists groups.
Inputs: include_groups.
list_materialsARead-only
List the materials in the model: name, RGB color, transparency, texture file.
Inputs: no named parameters.
list_tagsARead-only
List tags (layers): name, visible/hidden, and number of entities using the tag (including inside definitions).
Inputs: no named parameters.
model_infoARead-only
Overview of the open model: path, units, bounding box size (mm), number of top-level groups/components/ faces/edges, and number of tags, materials, definitions, scenes and selected entities.
Inputs: no named parameters.
new_modelBDestructive
Create a new (empty) model.
Inputs: no named parameters.
open_modelCDestructive
Open a .skp file in SketchUp.
Inputs: path (required).
pingARead-only
Check the connection to SketchUp: returns the SketchUp and Ruby versions, the open model name, and the versions of the bridge in SketchUp and of the MCP server (warns if the bridge is older than the bundled one).
Inputs: no named parameters.
quantity_takeoffARead-only
Quantity takeoff: walks the whole model recursively (or only the selection) and totals by tag or material: face area (m2, one side), face count, total edge length (m), solid volume (m3) and instance count per component. Untagged/unpainted entities inherit from their parent group.
Inputs: group_by, include_hidden, selection_only.
run_rubyADestructive
Run arbitrary Ruby code in SketchUp (Ruby API). Use it when the other tools are not enough. Useful objects: Sketchup.active_model, model.entities, model.selection. Internal units are inches: use 1000.mm, x.to_mm. The whole snippet is one Undo step. Returns the last value (inspect) and the puts output. Rules: do NOT call start_operation/commit_operation (the bridge already wraps the code in one Undo step); find entities with Sketchup.active_model.find_entity_by_id(id); check face.normal before pushpull; vertex coordinates inside a group are local (multiply by the parent group transformation); end with a value or puts; never call exit.
Inputs: code (required).
save_modelADestructive
Save the model. Empty path = overwrite the current file; with path = Save As.
Inputs: path.
screenshotARead-only
Capture the SketchUp viewport and return the image so Claude can see it directly (to check modelling results). Empty view = keep the current view. With view, the camera changes only temporarily for the capture and the previous view is restored afterwards.
Inputs: view, width, height, max_size.
select_entitiesBIdempotent
Select entities by id in SketchUp (so the user can see them, or for later tools to use).
Inputs: entity_ids (required), clear.
selection_infoARead-only
Info on the selected entities: id, type, name, tag, material, bounding box (mm), face area (m2), solid volume (m3). The ids are used by the edit/delete tools.
Inputs: limit.
set_materialAIdempotent
Apply a material to entities (entity_ids or the current selection). A missing material is created with color; an EXISTING material keeps its color (unless update_existing=true).
Inputs: material (required), color, back_too, entity_ids, +1 more.
set_tagAIdempotent
Assign a tag to entities (entity_ids or the current selection). A missing tag is created.
Inputs: tag (required), entity_ids.
set_viewAIdempotent
Set a standard view and zoom extents. iso defaults to perspective, the other views to parallel projection.
Inputs: view, perspective, zoom_extents.
transform_entitiesA
Move / rotate / scale entities. Empty entity_ids = use the current selection. translate [dx,dy,dz] mm; rotate_deg about axis (default Z) at pivot (mm, default entity center); scale is a uniform factor. Order applied: scale -> rotate -> translate.
Inputs: axis, pivot, scale, translate, +2 more.
undoADestructive
Undo the last step in SketchUp (every model-editing tool is one Undo step).
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 26 tools
The set separates inspection, creation, editing, and export well; the main ambiguities are screenshot/export_png/export_file, which all capture or export imagery, and set_view's view parameter. Descriptions largely clarify these boundaries, so an agent can still choose correctly.
All names use lower snake_case, which is predictable. Most follow verb_noun (list_tags, create_box, set_material), but several are noun-only (model_info, selection_info, quantity_takeoff, screenshot) and a few are single words (ping, undo), so it is not a perfectly uniform verb_noun pattern.
With 26 tools, the server is on the heavy side for an MCP tool set, but the breadth of SketchUp operations means most tools have a distinct job. It sits just above the typical 3-15 range, making it borderline but not clearly bloated.
Core lifecycle is covered: create (box/shape/lines/component), read (model_info, list_*, selection_info), update (transform, set_material, set_tag), delete, and undo, plus run_ruby as an escape hatch. Gaps remain for tag/material deletion, scene management, redo, and some component/definition operations, but agents can work around most via run_ruby.
Maintenance
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Convert Revit files to XKT, IFC, or DWG and query BIM data via natural language.
Find, read, create and edit Plainer files with Claude Code or Codex. Approve access in your browser.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
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
- 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
- AlicenseAqualityDmaintenanceControls SketchUp via AI assistants, enabling 3D model creation programmatically through the Model Context Protocol.2115MIT
- AlicenseCqualityBmaintenanceEnables MCP clients to inspect and modify SketchUp models through a local authenticated bridge, covering entity creation and editing, geometry, materials, tags, cameras, scenes, transactions, snapshots, and file or view export. It also offers an optional full SketchUp Ruby API execution channel and batch operations for furniture, architectural, and analysis tasks.371MIT