Ringo SketchUp MCP
This server is a local MCP bridge that lets an AI agent inspect and modify a desktop SketchUp model safely, visually, and atomically.
Inspect bridge/profile/capabilities, model info/stats, entities, selection, materials, tags, scenes, and camera state.
Create geometry such as boxes, cylinders, arbitrary meshes, and extrusions.
Edit entities by transforming, updating names/tags/visibility/locks, deleting, duplicating, grouping, and making components unique.
Assign materials and manage material colors/textures/PBR, tags, and visibility.
Control the camera, save/select scenes, capture or export views as images for visual verification.
Take model snapshots and diff changes; undo/redo operations and run up to 100 mutations atomically with
batch_run.Save or export the model to files with overwrite protection.
Optionally execute trusted SketchUp Ruby when explicitly enabled.
Operate with safety features: model/context checks, persistent IDs/paths, undo transactions, loopback-only networking, token authentication, and Ruby disabled by default.
Provides tools for interacting with SketchUp models through a native Ruby extension, including querying model entities, creating and editing geometry, managing materials and tags, controlling cameras and scenes, running transactions, exporting files, and executing SketchUp Ruby API commands.
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., "@Ringo SketchUp MCP create a 2000 x 1000 x 50 mm table top and export current view as PNG"
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.
Ringo SketchUp MCP
让 AI 走进你的 SketchUp:查询、建模、编辑,再亲眼看看结果。
一座连接 MCP Agent 与桌面 SketchUp 的本地桥梁:通用、安全、可撤销。
快速开始 · 接入 Agent · 工具一览 · 多开实例 · 安全边界 · 常见问题
💬 "先确认当前 SketchUp 模型。创建一个 1200 × 600 × 30 毫米的桌面,底部离地 720 毫米;再做四条 40 × 40 毫米的桌腿,起好名字,最后调整相机把视图给我看看。"
只要说一句话,Agent 就会依次调用
model_get_info→entity_create_box×5 →camera_set→view_capture,在你的 SketchUp 里搭出这张桌子,再把截图带回对话。
✨ 亮点
🧩 通用工具,不写死模型
37 个类型化工具,覆盖查询、几何创建、变换、材质、标签、相机、场景、导出等操作。桌子、房子、零件都使用同一套 API,不需要为某个特定模型改服务器代码。
👀 让 AI 看得见
view_capture 不用指定保存路径,直接把 PNG 作为 MCP 图片返回。Agent 建完模型可以自己检查结果,发现问题再修改。
↩️ 一切皆可撤销
每次修改都是一个 SketchUp Undo 事务。batch_run 把最多 100 步操作合成一次撤销,中间任一步失败就整体回滚。
🎯 不会改错地方
persistent_id、完整实例路径、模型会话与编辑上下文共同守护每一次修改。共享组件的引用有歧义时直接拒绝,锁定的祖先也受到保护。
🔒 默认安全
只监听 127.0.0.1,每个请求都要校验随机 token。任意 Ruby 执行默认关闭;日志不记录 token、参数或代码。
🪟 多开不打架
用 profile 给每个 SketchUp 分配独立的端口、token 和 MCP 服务名,两个项目可以同时由 AI 驱动,互不串线。
Related MCP server: CDT-SketchUp
🏗 工作原理
flowchart LR
A["🤖 MCP Agent<br/>ChatGPT · Codex · Claude<br/>Cursor · VS Code"]
B["⚙️ Node.js MCP 服务<br/>参数校验 · 模型绑定<br/>图片返回 · 进度"]
C["💎 SketchUp Ruby 扩展<br/>UI 线程任务队列<br/>Undo 事务 · 引用解析"]
D[("🏠 SketchUp 模型")]
A -- "stdio · MCP" --> B
B -- "TCP 127.0.0.1<br/>JSON-RPC + token" --> C
C --> DNode 层负责标准 MCP 协议:用 zod 校验全部参数,记住最近读取的模型会话,并把截图转换成 MCP 图片。
Ruby 层运行在 SketchUp 内部:用非阻塞 I/O 接收请求,在 UI 线程上按队列执行,每次修改都包在 Undo 事务中。
两层通过带认证的回环 JSON-RPC 通信,协议主版本独立演进,次版本差异通过 capabilities 协商。
📋 环境要求
项目 | 要求 |
SketchUp | 桌面版,推荐 2021 及以上(网页版、iPad 版不适用) |
操作系统 | Windows ✅ 已在 SketchUp 26.2.243 上完成实机回归macOS 🧪 安装路径、CI 与 Ruby 实现共用,尚未完成实机验收 |
Node.js | |
AI 客户端 | 任意支持 stdio MCP 的客户端 |
🚀 快速开始
1. 准备环境:安装桌面 SketchUp 和 Node.js,并先启动一次 SketchUp,让它生成用户插件目录。
2. 获取代码并一键安装
git clone https://github.com/Ringophilia/Ringo-Sketchup-MCP.git
cd Ringo-Sketchup-MCP
npm run setupWindows 也可以直接双击
setup.cmd;macOS 可以在终端运行sh setup.command。
安装脚本会完成:安装依赖 → 构建服务 → 备份并安装扩展 → 生成本机客户端配置。Ruby 脚本执行默认关闭,普通建模和图片预览都不需要它。
3. 重启 SketchUp,接入 Agent,运行体检
npm run doctordoctor 会逐项检查构建、配置、扩展文件、实时连接和版本匹配,任何一项失败都会给出下一步操作建议。
4. 说出第一句话
使用 sketchup MCP,先调用
model_get_info告诉我当前模型,然后用view_capture看看当前视图。
能看到截图,就说明一切就绪 🎉。更多建模示例见 使用指南。
🔌 接入你的 Agent
npm run setup(或 npm run config:agents)会在 .agent-config/ 下生成配置片段。片段中使用绝对路径,路径含空格或中文也没问题,并且不包含 token。
生成文件 | 适用客户端 |
| ChatGPT 桌面版、Codex CLI、Codex IDE 扩展 |
| Claude Desktop、Claude Code、Cursor 等使用 |
| VS Code / GitHub Copilot |
{
"mcpServers": {
"sketchup": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/Ringo-Sketchup-MCP/dist/mcp-server.js"]
}
}
}各客户端的详细导入步骤,以及网页版、云端 Agent 的接入边界,见 Agent 接入指南。
能列出工具 ≠ 已连上 SketchUp。 只有
bridge_status调用成功,才说明 Node 服务已经和 SketchUp 握手。
🧰 工具一览
类别 | 工具 |
🩺 状态与模型 |
|
🔍 查询与选择 |
|
🧱 几何创建 |
|
✏️ 编辑 |
|
🎨 材质与标签 |
|
🎥 相机与场景 |
|
🔁 事务与比较 |
|
🖼 图片与文件 |
|
🧪 高级 API |
|
每个工具都会返回 structuredContent。成功时包含数据、警告、任务 ID、执行耗时和排队耗时;失败时给出明确的错误码。view_export 生成的图片不超过 4 MiB 时,也会附带返回图片内容。
先读再改:首次修改前调用
model_get_info。服务会记住模型会话,并为后续修改自动补上model_id;切换模型后需要重新读取。创建、选择、分组这类依赖编辑上下文的操作还会检查active_path。单位:输入和输出默认都是毫米。创建和增量变换使用父容器坐标;返回的
transform是世界变换(列主序,平移使用请求的单位)。matrix输入会替换局部变换,不要直接复用世界矩阵。嵌套与共享:嵌套实体使用完整
path引用;parent: {path: [...]}指定在哪个容器里创建。共享组件的同一个 ID 可能对应多个路径,这种情况下必须显式提供路径。修改共享定义会影响所有实例;想要独立修改,先对祖先调用entity_make_unique,再重新查询。批量:
batch_run复用单个工具的参数校验和默认值,所有步骤在同一个 Undo 事务中执行,任一步失败就整体回滚。大模型分页:
entity_list默认取到一页就返回。total_exact: false表示总数只是下界,沿next_offset继续翻页;需要精确总数时传include_total: true。遇到数量上限或约 500 ms 的遍历预算时会返回truncated: true,这时应缩小父级范围。覆盖保护:保存和导出默认不覆盖已有文件,需要显式设置
overwrite: true。
更多示例见 使用指南。
🪟 同时驱动多个 SketchUp
每个 profile 拥有独立的端口、token、配置文件和 MCP 服务名,两个 SketchUp 不会再争用 9876 端口。
npm run setup -- --profile project-a --name "Project A" --port 9876
npm run setup -- --profile project-b --name "Project B" --port 9877把
.agent-config/project-a/和.agent-config/project-b/中的服务合并到客户端配置里,得到sketchup-project-a和sketchup-project-b两个服务。在每个 SketchUp 窗口中打开 Extensions → Ringo SketchUp MCP → Select Profile,选择对应的 profile。
让 LLM 修改前先调用目标服务的
bridge_status,核对data.instance.profile_id和profile_name。
profile ID 只是你自定义的路由标签。各服务之间的
model_id、实体路径和快照不能互换,服务也不会根据前台窗口猜测目标。重复的端口会在安装时被直接拒绝。
🔒 安全与运行边界
方面 | 设计 |
网络 | 只监听 |
认证 | 握手和每个请求都校验随机 token(至少 32 位);客户端配置中不包含 token |
资源上限 | 最多 16 个客户端、128 个排队任务,单帧 4 MiB |
排队保护 | 过期或已取消的任务不会执行;排队期间模型或编辑上下文发生变化时拒绝执行;不同客户端的取消请求互相隔离 |
Ruby 执行 | 默认关闭;开启后以本机用户权限运行,只应对可信客户端开放 |
日志 | 不记录 token、完整参数或 Ruby 代码 |
⚠️ 超时不等于操作没有执行。 断线后服务不会自动重放修改。遇到超时,请先查看
bridge_status中的最近任务和实际模型,再决定是否重试。正在运行的 Ruby 无法被安全地强制中止,不要提交可能无限循环的脚本。
快照只保存容器和根实体的元数据(最多 10,000 项,保留最近 10 个),不做逐顶点的几何比较。
⚙️ 配置
平台 | 默认配置文件 |
Windows |
|
macOS |
|
自定义 | 通过环境变量 |
可以用环境变量覆盖:SKETCHUP_PORT、SKETCHUP_TOKEN、SKETCHUP_TIMEOUT_MS、SKETCHUP_ENABLE_RUBY_EVAL。Node 端的请求超时也可以写在配置文件的 timeout_ms 中(单位毫秒,范围 100–600000,默认 60000),环境变量优先。
从 Finder 启动的 Mac 应用通常不会继承 shell 环境变量,建议直接使用默认配置文件。
npm run setup -- --year 2026 # 指定 SketchUp 版本(默认选择最新版本)
npm run setup -- --plugins "/custom/Plugins" # 自定义插件目录
npm run setup -- --dry-run # 只显示安装计划,不修改任何文件
npm run setup -- --enable-ruby # 开启完整 Ruby API(需要重启 SketchUp)升级会完整备份旧扩展(loader 与实现目录),安装失败时自动恢复扩展和原配置。备份位于配置目录下的
backups/,安装完成后会打印具体位置。移动项目目录或升级 Node 之后,重新运行
npm run config:agents并更新客户端配置。已有开发环境也可以分步执行:
npm ci→npm run build→npm run install:extension→npm run config:agents。
npm run doctor # 完整体检
npm run doctor -- --json # 机器可读输出
npm run doctor -- --offline # 只检查安装文件,不能证明已连上 SketchUp
npm run doctor -- --profile project-a通过 Extension Manager 手动安装 RBZ 的用户没有安装记录,可以用 --plugins PATH 指定检查位置。
❓ 常见问题
现象 | 处理方式 |
首次修改提示先读取模型 | 调用 |
| 重新读取模型信息,重新确认目标 |
| 用 |
| 查看 |
| 缩小父级范围,降低深度或图片尺寸 |
工具能列出但连不上 SketchUp | 打开桌面模型,确认扩展已启用,再运行 |
doctor 提示版本不一致 | 运行 |
doctor 提示认证失败 | 确认两端使用同一个配置目录,保留原 token,重启两端 |
完整的排错表见 使用指南 · 常见错误。
🧪 开发与验证
npm run check # 构建 + Node 测试
npm run check:ruby # Ruby 语法检查(可用 RUBY 指定解释器)
npm run test:ruby # Ruby 行为测试(需要 minitest)
npm run package:rbz # 生成 RBZ 和 SHA-256 摘要到 release/npm run test:live # 通用建模操作
npm run test:references # 嵌套、共享组件、锁定、上下文切换
npm run test:performance # 5000 实例大模型
node scripts/security-test.mjs这些脚本需要根编辑上下文并开启 Ruby。它们会创建并清理 QA 对象,但会改变 Undo 历史和模型的修改标记。
CI 覆盖 Windows / macOS / Linux × Node 22 / 24,以及 Ruby 2.7 / 3.2 / 3.3 的语法与行为测试,但不运行 SketchUp 图形宿主。RBZ 在 Windows 和 macOS 上通用,Node 服务仍然需要保留。
📚 文档
文档 | 内容 |
建模示例、坐标与嵌套、批量操作、大模型查询、错误处理 | |
各客户端的导入步骤与云端接入边界 | |
版本原则、能力降级、macOS 说明 | |
每个版本的实机验收证据 | |
已知问题与后续路线图 | |
版本变更 |
🤝 参与贡献
欢迎提交 Issue、改进文档和发起 Pull Request,请先阅读 贡献指南。发现安全问题时,请通过 私密漏洞报告 联系,不要公开发布。
项目原则:工具保持通用;仅限回环通信;认证必选;Ruby 执行需要显式开启。
📄 许可证
MIT License:允许个人和商业使用,分发时请保留许可和版权声明。
Available Tools
37 toolsbatch_runA
Run 1–100 typed model mutations in a single atomic undo operation. Ruby, save, undo, and nested batches excluded.
Inputs: commands (required), model_id, active_path, operation_name.
bridge_statusARead-onlyIdempotent
Inspect connection, selected SketchUp profile/instance, capabilities, queue and recent request states. Runtime permissions and optional APIs are discovered here.
Inputs: no named parameters.
camera_getBRead-onlyIdempotent
Read camera eye, target and up vector.
Inputs: no named parameters.
camera_setC
Set camera and optionally frame an entity or the whole model.
Inputs: up, eye, fov, path, +8 more.
entity_create_boxC
Create a box toward positive Z with an undo transaction. Default unit is mm.
Inputs: size (required), tag, name, unit, +5 more.
entity_create_cylinderC
Create a positive Z cylinder, in mm, with optional smooth sides.
Inputs: height_mm (required), radius_mm (required), tag, name, +8 more.
entity_create_meshC
Create arbitrary grouped geometry from vertices and zero-based face indices. Triangulate nonplanar faces. Supports smooth shading.
Inputs: faces (required), vertices (required), tag, name, +7 more.
entity_deleteBDestructive
Delete an existing entity in an undoable operation.
Inputs: path, model_id, entity_id.
entity_duplicateC
Copy a group or component; offset in the parent coordinate system.
Inputs: name, path, unit, model_id, +2 more.
entity_extrudeB
Extrude a planar polygon along its normal. XY polygons are oriented toward positive Z.
Inputs: points (required), distance (required), tag, name, +6 more.
entity_groupC
Group existing entities in the current edit context.
Inputs: entity_ids (required), name, model_id, active_path.
entity_inspectBRead-onlyIdempotent
Inspect persistent ID, instance path, world bounds, solid status and transform. Translation entries in matrices use the requested unit.
Inputs: path, unit, model_id, entity_id.
entity_listBRead-onlyIdempotent
Paginate entities with paths and world bounds. Recursive traversal distinguishes shared component instances. Use scan_limit for large models; total_exact reports whether total is complete.
Inputs: tag, name, path, type, +10 more.
entity_make_uniqueC
Make a component instance or group independent of shared geometry.
Inputs: path, model_id, entity_id.
entity_set_materialC
Assign material to an instance or its direct faces. Faces scope makes instances unique first.
Inputs: material (required), path, color, scope, +2 more.
entity_transformB
Transform a group/instance in its parent coordinates. Scale, rotate, then translate. Matrix replaces transform; column major with translation in unit. Axis-angle preferred; legacy Euler X,Y,Z supported.
Inputs: axis, path, unit, pivot, +7 more.
entity_updateC
Set entity name, tag, visibility or lock state.
Inputs: tag, name, path, hidden, +3 more.
materials_listBRead-onlyIdempotent
List material color, alpha and texture status.
Inputs: no named parameters.
materials_setC
Create/update material. Optional PBR roughness gracefully falls back on older SketchUp.
Inputs: name (required), alpha, color, texture, +3 more.
model_diffBRead-onlyIdempotent
Compare entity metadata with a snapshot; reports additions, deletions and changes, not individual mesh vertices.
Inputs: snapshot_id (required), model_id, active_path.
model_exportC
Export through the installed SketchUp exporter selected by file extension. Availability depends on the host edition/version.
Inputs: path (required), options, model_id, overwrite, +1 more.
model_get_infoARead-onlyIdempotent
Get model session ID, path, units, edit context and runtime capabilities.
Inputs: no named parameters.
model_redoCDestructive
Redo when supported by this SketchUp version.
Inputs: model_id, active_path.
model_saveB
Save SKP to an absolute path. Explicit overwrite flag protects existing files.
Inputs: path (required), model_id, overwrite, active_path.
model_snapshotCRead-onlyIdempotent
Capture bounded entity/path metadata for subsequent changes comparison.
Inputs: model_id, active_path.
model_statsCRead-onlyIdempotent
Count entities through instance paths, materials, tags and scenes. Results are bounded by max_entities.
Inputs: model_id, active_path, max_entities.
model_undoCDestructive
Undo the most recent SketchUp operation.
Inputs: model_id, active_path.
scene_clearADestructive
Erase all model entities in one undoable operation. Requires root edit context.
Inputs: model_id, active_path.
scenes_listBRead-onlyIdempotent
List saved SketchUp scenes.
Inputs: no named parameters.
scenes_setB
Save/update the current view as a scene, or select an existing scene.
Inputs: name (required), action, model_id, active_path.
selection_getBRead-onlyIdempotent
Read current selected entities.
Inputs: no named parameters.
selection_setC
Set selection using existing entity IDs; empty list clears selection.
Inputs: entity_ids (required), model_id, active_path.
sketchup_run_rubyADestructive
Execute trusted SketchUp Ruby on the UI thread. Requires ruby_enabled. Default transaction rolls back failures; do not start nested SketchUp operations. Captures stdout. Running Ruby cannot be forcibly cancelled safely.
Inputs: code (required), model_id, active_path, transaction, +1 more.
tags_listBRead-onlyIdempotent
List tags and visibility.
Inputs: no named parameters.
tags_setC
Create a tag or set its visibility.
Inputs: name (required), visible, model_id, active_path.
view_captureBRead-onlyIdempotent
See the current SketchUp view directly as an image. No output path required. Use after modeling to visually verify the result.
Inputs: width, height, model_id, active_path, +1 more.
view_exportC
Export PNG/JPG from SketchUp for visual verification.
Inputs: path (required), width, height, model_id, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Most tools target a distinct resource and action, and descriptions clearly distinguish similar pairs such as view_capture vs. view_export and entity_list vs. entity_inspect. Some layering overlap exists between batch_run/sketchup_run_ruby and individual mutation tools, but the intended usage is still understandable.
The dominant pattern is resource_action or resource_action_object, applied consistently across entity_, model_, camera_, selection_, tags_, scenes_, and materials_ groups. Minor deviations like model_get_info and model_stats are readable but slightly break the otherwise predictable scheme.
At 37 tools, the surface is heavy for an MCP server and exceeds the typical well-scoped 3–15 range. While SketchUp is a broad domain, the count still feels excessive and likely increases selection overhead.
The set covers essential modeling lifecycle operations: creation, transformation, editing, deletion, grouping, materials, tags, scenes, camera, selection, undo/redo, save/export, snapshots, and Ruby escape hatches. Gaps like material/tag/scene deletion and import are minor and can largely be handled through Ruby or workarounds.
Maintenance
Related MCP Connectors
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Read and edit the Revit 2024–2027 model on your PC. Needs the free Revit MCP add-in.
Create, inspect, validate, and save editable 3D building scenes with Pascal's MCP server.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables controlling SketchUp from MCP-compatible clients via a stdio Python server that bridges to a Ruby plugin, supporting component operations, material assignment, scene export, arbitrary Ruby evaluation, and wood joinery tools.1013MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to inspect and manipulate live SketchUp models through a safe loopback bridge, supporting geometry creation, component/group operations, tags, materials, and transformations with persistent-ID safety.MIT
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to drive Blockbench Desktop locally for Minecraft model, UV, texture, animation, and export workflows. It provides typed operations, high-level task workflows, native controls, and inspection/verification tools over an authenticated loopback connection.3-
- AlicenseAqualityCmaintenanceConnects MCP-aware AI clients to a live SketchUp session so models can be built and edited through natural-language prompts. Exposes typed tools for geometry creation, materials, booleans, edge chamfers/fillets, joinery, scene export, model introspection, viewport screenshots, and an optional arbitrary-Ruby escape hatch.24MIT