Skip to main content
Glama
Ringo SketchUp MCP
by Ringophilia

Ringo SketchUp MCP

让 AI 走进你的 SketchUp:查询、建模、编辑,再亲眼看看结果。

一座连接 MCP Agent 与桌面 SketchUp 的本地桥梁:通用、安全、可撤销。

CI Version License: MIT Node SketchUp MCP

快速开始 · 接入 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 --> D
  • Node 层负责标准 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

22 或 24 LTS

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 setup

Windows 也可以直接双击 setup.cmd;macOS 可以在终端运行 sh setup.command。

安装脚本会完成:安装依赖 → 构建服务 → 备份并安装扩展 → 生成本机客户端配置。Ruby 脚本执行默认关闭,普通建模和图片预览都不需要它。

3. 重启 SketchUp,接入 Agent,运行体检

npm run doctor

doctor 会逐项检查构建、配置、扩展文件、实时连接和版本匹配,任何一项失败都会给出下一步操作建议。

4. 说出第一句话

使用 sketchup MCP,先调用 model_get_info 告诉我当前模型,然后用 view_capture 看看当前视图。

能看到截图,就说明一切就绪 🎉。更多建模示例见 使用指南。

🔌 接入你的 Agent

npm run setup(或 npm run config:agents)会在 .agent-config/ 下生成配置片段。片段中使用绝对路径,路径含空格或中文也没问题,并且不包含 token。

生成文件

适用客户端

codex.toml

ChatGPT 桌面版、Codex CLI、Codex IDE 扩展

mcp.json

Claude Desktop、Claude Code、Cursor 等使用 mcpServers 的客户端

vscode.json

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 握手。

🧰 工具一览

类别

工具

🩺 状态与模型

bridge_status · model_get_info · model_stats

🔍 查询与选择

entity_list · entity_inspect · selection_get · selection_set

🧱 几何创建

entity_create_box · entity_create_cylinder · entity_create_mesh · entity_extrude

✏️ 编辑

entity_transform · entity_update · entity_delete · entity_duplicate · entity_group · entity_make_unique

🎨 材质与标签

entity_set_material · materials_list · materials_set · tags_list · tags_set

🎥 相机与场景

camera_get · camera_set · scenes_list · scenes_set

🔁 事务与比较

batch_run · model_undo · model_redo · model_snapshot · model_diff

🖼 图片与文件

view_capture · view_export · model_save · model_export · scene_clear

🧪 高级 API

sketchup_run_ruby(默认关闭)

每个工具都会返回 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
  1. 把 .agent-config/project-a/ 和 .agent-config/project-b/ 中的服务合并到客户端配置里,得到 sketchup-project-a 和 sketchup-project-b 两个服务。

  2. 在每个 SketchUp 窗口中打开 Extensions → Ringo SketchUp MCP → Select Profile,选择对应的 profile。

  3. 让 LLM 修改前先调用目标服务的 bridge_status,核对 data.instance.profile_id 和 profile_name。

profile ID 只是你自定义的路由标签。各服务之间的 model_id、实体路径和快照不能互换,服务也不会根据前台窗口猜测目标。重复的端口会在安装时被直接拒绝。

🔒 安全与运行边界

方面

设计

网络

只监听 127.0.0.1,内部 TCP 端口不是 HTTP 端点

认证

握手和每个请求都校验随机 token(至少 32 位);客户端配置中不包含 token

资源上限

最多 16 个客户端、128 个排队任务,单帧 4 MiB

排队保护

过期或已取消的任务不会执行;排队期间模型或编辑上下文发生变化时拒绝执行;不同客户端的取消请求互相隔离

Ruby 执行

默认关闭;开启后以本机用户权限运行,只应对可信客户端开放

日志

不记录 token、完整参数或 Ruby 代码

⚠️ 超时不等于操作没有执行。 断线后服务不会自动重放修改。遇到超时,请先查看 bridge_status 中的最近任务和实际模型,再决定是否重试。正在运行的 Ruby 无法被安全地强制中止,不要提交可能无限循环的脚本。

快照只保存容器和根实体的元数据(最多 10,000 项,保留最近 10 个),不做逐顶点的几何比较。

⚙️ 配置

平台

默认配置文件

Windows

%APPDATA%/RingoSketchUpMCP/config.json

macOS

~/Library/Application Support/RingoSketchUpMCP/config.json

自定义

通过环境变量 SKETCHUP_MCP_CONFIG 指定

可以用环境变量覆盖: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 指定检查位置。

❓ 常见问题

现象

处理方式

首次修改提示先读取模型

调用 model_get_info,确认标题和路径后再继续

-32007 模型或编辑上下文变化

重新读取模型信息,重新确认目标

-32008 引用失效或有歧义

用 entity_list 重新查询完整路径,不要猜 ID

-32003 超时或取消

查看 bridge_status 和实际模型,执行结果可能未知

-32005 结果或查询过大

缩小父级范围,降低深度或图片尺寸

工具能列出但连不上 SketchUp

打开桌面模型,确认扩展已启用,再运行 npm run doctor

doctor 提示版本不一致

运行 npm run setup,然后重启 SketchUp

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 服务仍然需要保留。

📚 文档

文档

内容

使用指南

建模示例、坐标与嵌套、批量操作、大模型查询、错误处理

Agent 接入指南

各客户端的导入步骤与云端接入边界

兼容策略

版本原则、能力降级、macOS 说明

验证记录

每个版本的实机验收证据

提升计划

已知问题与后续路线图

更新日志

版本变更

🤝 参与贡献

欢迎提交 Issue、改进文档和发起 Pull Request,请先阅读 贡献指南。发现安全问题时,请通过 私密漏洞报告 联系,不要公开发布。

项目原则:工具保持通用;仅限回环通信;认证必选;Ruby 执行需要显式开启。

📄 许可证

MIT License:允许个人和商业使用,分发时请保留许可和版权声明。

Available Tools

37 tools
batch_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_statusA
Read-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_getB
Read-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_deleteB
Destructive

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_inspectB
Read-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_listB
Read-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_listB
Read-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_diffB
Read-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_infoA
Read-onlyIdempotent

Get model session ID, path, units, edit context and runtime capabilities.

Inputs: no named parameters.

model_redoC
Destructive

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_snapshotC
Read-onlyIdempotent

Capture bounded entity/path metadata for subsequent changes comparison.

Inputs: model_id, active_path.

model_statsC
Read-onlyIdempotent

Count entities through instance paths, materials, tags and scenes. Results are bounded by max_entities.

Inputs: model_id, active_path, max_entities.

model_undoC
Destructive

Undo the most recent SketchUp operation.

Inputs: model_id, active_path.

scene_clearA
Destructive

Erase all model entities in one undoable operation. Requires root edit context.

Inputs: model_id, active_path.

scenes_listB
Read-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_getB
Read-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_rubyA
Destructive

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_listB
Read-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_captureB
Read-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

    C2.9/5.0

    Scored across 37 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      10
      13
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      C
      maintenance
      Connects 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.
      24
      MIT