SketchUp MCP

SketchUp MCP

English | 越南语

SketchUp MCP 让 Claude 直接在你打开的 SketchUp 模型中工作。你可以用日常语言以任何语言提出需求，Claude 会读取模型、按标签或材质进行工程量统计、创建几何体、分配材质和标签、截图检查自己的工作，并导出图像和文件。它以 Claude Desktop 扩展（.mcpb）的形式提供，运行在 Claude Desktop 内置的 Node.js 上，另附一个适用于 SketchUp 的小型 Ruby 扩展（SU MCP Bridge）。你无需安装 Python 或 Node.js。

当前版本：1.3.0 - 从 Releases 下载。它也已列入官方 MCP Registry，名称为 io.github.2ez4gcx/sketchup-mcp。

功能

29 个工具，全部使用毫米（面积单位为 m²，体积单位为 m³，角度单位为度，Z 轴朝上）：

亮点：

• 专业标签：Claude 会像整理饰面表一样为模型中的对象添加标签，格式为 CODE-NN description（例如 FL-01 Engineered oak floor 12mm、WL-02 Walnut veneer panel、CL-01 Gypsum flat ceiling）：每项规格对应一个标签，因此一个标签就是工程量清单中的一行。代码涵盖地面（FL）、踢脚线（SK）、墙面饰面（WL）、隔墙（PA）、天花板（CL）、檐口线脚（CO）、门（DR）、窗（WN）、玻璃（GL）、固定式木作（JN）、家具（FN）、照明（LT）、卫生洁具（SN）、设备（EQ）、窗帘（CU）、装饰（DE）、现有结构（EX）和参考项（RF）。每个标签都会放入对应类别的文件夹（SketchUp 2021+），并应用类别颜色；该颜色会显示在 Tags 面板的 按标签着色 中。如果模型中已有标签方案，则沿用该方案。
• 室内工程量清单（interior_takeoff）：每个标签对应一行，并使用该类别所需的单位：地面和天花板以 m² 计（每块板只计算一次，不论其表面朝向如何；倾斜天花板按实际面积计算），墙面、隔墙和玻璃按单面面积（m²）计（如果门或窗只切穿墙面的一侧，则扣除其面积），踢脚线和檐口线脚按米计（也包括使用 Follow Me 沿房间制作的线条），窗帘按宽度 x 高度计，现有结构按 m³ 计，其他项目均按件数计。斜向绘制的墙面按直墙测量。清单会按类别汇总，并显示警告：未包含在任何带标签对象中的几何体、整个房间被绘制成一个箱体、位于隐藏标签上的对象（除非另有要求，否则不计量）、嵌套在饰面中的组件没有自己的标签。清单可以保存为 CSV 文件，以便在 Excel 中使用。
• 按房间统计数量：将每个房间的对象放入一个命名组中，且该组不添加标签（例如 Living room；嵌套组会生成 Level 2 / Bedroom 1），然后 by_room 会按房间拆分每一行。CSV 中会在总计旁为每个房间添加一列。make_group 可创建房间组。
• 按标签或材质统计工程量：遍历整个模型（或仅遍历所选对象），汇总面面积、面数、边长、实体体积和组件实例数。未添加标签或未着色的实体会继承其父级组的标签或材质。
• 可恢复视图的截图：Claude 可直接查看视口图像。当它请求特定视图（等轴测、俯视、正视等）时，仅在截图过程中更改相机，之后会恢复你自己的视图。
• 将 run_ruby 作为一次撤销操作：没有合适的专用工具时，Claude 可以运行 Ruby API 代码。整个代码片段会作为一次撤销操作。发生错误时会回滚部分更改，并在错误消息中指出代码片段中的出错行。
• 每次模型编辑都是一次撤销操作，在 SketchUp 的“编辑”菜单中命名为 MCP: ...，因此按 Ctrl+Z 始终只会撤销 Claude 的一项操作。
• install_sketchup_bridge：Claude 会自行安装或更新 Ruby bridge。它会将文件复制到所有至少打开过一次的 SketchUp 版本的 Plugins 文件夹中（dry_run 只会报告将要执行的操作）。
• 安全默认行为：除非 Claude 传入 update_existing=true，否则现有材质会保留其颜色。delete_entities 仅按明确指定的 id 删除，绝不按选择内容删除。发生超时后，错误消息会告知 Claude 命令是否可能已经运行，避免它重复编辑并创建重复几何体。
• 版本检查：ping 会显示 Claude 正在控制的模型，并在 SketchUp 中的 bridge 版本早于扩展中附带的版本时发出警告。
• SketchUp 菜单（Extensions > SU MCP Bridge）：Start server、Stop server、Status、Open log file、Change port...。

演示

这个演示凉亭完全通过 MCP 工具（create_box、create_shape、run_ruby、set_material、set_tag）搭建，随后使用 screenshot 和 quantity_takeoff 进行检查——总计调用了 82 次工具。

工作原理

Claude Desktop
    |  MCP over stdio
    v
sketchup-mcp-1.3.0.mcpb        Node.js MCP server, runs on the Node built into Claude Desktop
    |  one JSON request per command, TCP 127.0.0.1:9876 (localhost only)
    v
SU MCP Bridge                  Ruby extension inside SketchUp, starts with SketchUp
    |  SketchUp Ruby API
    v
the open SketchUp model

要求

• Claude Desktop（当前版本，包含 Settings > Extensions），并已登录 Claude 账号。
• SketchUp 2017 或更高版本（桌面版）。已在 SketchUp 2021 和 2023 上测试。安装桥接插件前，必须至少打开过每个 SketchUp 版本一次。
• Windows 10/11：已测试。macOS：未经测试（该扩展已打包为 macOS 版本，安装程序也能识别 macOS Plugins 文件夹，但尚未在 Mac 上试用）。
• 仅在从源代码构建时需要：Node.js 18 或更高版本，以及 npm。

下载

从最新版本获取文件：

安装

1. 在 Claude Desktop 中安装扩展。 打开 Settings > Extensions，然后将 sketchup-mcp-1.3.0.mcpb 拖放到窗口中，或点击 Advanced settings > Install Extension... 并选择文件。点击 Install。此构建未经代码签名，因此 Claude Desktop 可能会警告该扩展未签名：仅安装来自本项目版本发布页的文件，或由你自行构建的文件。在 Microsoft Store 版 Claude 中，双击 .mcpb 文件不会打开安装界面，因此请通过 Settings 安装。

2. 在 SketchUp 中安装 SU MCP Bridge。 在新聊天中向 Claude 发送以下请求：

   在 SketchUp 中安装 SU MCP Bridge

   Claude 会调用 install_sketchup_bridge（点击 Allow），并列出已更新的 SketchUp 版本。也可以手动安装：Extensions > Extension Manager > Install Extension（SketchUp 2017-2020：Window > Extension Manager），然后选择 su_mcp.rbz。该插件未经数字签名。如果 SketchUp 拒绝加载，请在 Extension Manager 中将 Extension Loading Policy（齿轮图标）设为 Approve Unidentified Extensions，前提是你的 IT 策略允许这样做。

3. 完全退出 SketchUp，然后重新打开。 接着检查 Extensions > SU MCP Bridge > Status。应显示 SU MCP Bridge v1.3.0: RUNNING on 127.0.0.1:9876。最后，向 Claude 发送“Ping SketchUp”。

选项位于 Settings > Extensions > SketchUp MCP > Configure：桥接端口（默认值为 9876）和每条命令的超时时间（默认值为 120 s；对大型模型进行工程量统计时可调高）。如果更改端口，也要在 SketchUp 中更改（Extensions > SU MCP Bridge > Change port...），然后重启 SketchUp。

更新时，将新版 .mcpb 安装到旧版之上（会保留设置），让 Claude 再次安装桥接插件，然后重启 SketchUp。务必同时更新这两个部分。

示例提示词：mcpb/release-docs/en/SAMPLE_PROMPTS.txt。完整用户指南（HTML 和 PDF）位于发布包 zip 文件中（GUIDE_EN.html / GUIDE_EN.pdf），也附在每次版本发布中；源文件为 mcpb/release-docs/en/GUIDE.html。

其他 MCP 客户端

.mcpb 一键安装方式仅适用于 Claude Desktop，但该服务是基于 stdio 的标准 MCP 服务，因此任何能够启动本地 MCP 服务的客户端都可以使用。除 Claude Desktop 外，你还需要在 PATH 中配置 Node.js 18 或更高版本。

1. 获取服务。 .mcpb 文件是一个 zip 归档。将其解压到你选择的文件夹中，例如使用 Windows 10/11 自带的 tar，在命令提示符或 PowerShell 中解压（Git Bash 的 tar 无法读取该文件）。也可以将文件重命名为 .zip，然后使用 Extract All：

mkdir C:\Tools\sketchup-mcp
tar -xf sketchup-mcp-1.3.0.mcpb -C C:\Tools\sketchup-mcp

服务器路径为 C:/Tools/sketchup-mcp/server/index.mjs（在配置中使用正斜杠）。该文件夹还包含 桥接文件，因此任何客户端都可以使用 install_sketchup_bridge。你也可以从源代码构建 （mcpb/dist/bundle/server/index.mjs）。

2. 在客户端中注册（见下方示例）。可选环境变量：SKETCHUP_MCP_PORT（默认值为 9876） 和 SKETCHUP_MCP_TIMEOUT（每条命令的超时时间，单位为秒，默认值为 120）。如果客户端有自己的工具调用超时时间，请将其设置为 大于 SKETCHUP_MCP_TIMEOUT 的值。

3. 安装桥接程序，按照安装的第 2-3 步操作（让助手运行 install_sketchup_bridge，或使用 su_mcp.rbz），然后重启 SketchUp。

截图会以 MCP 图像的形式返回，因此模型必须支持图像输入才能“看到”截图。工具描述适用于任何模型，但不同模型的工具使用效果各不相同。如果已经注册了另一个名为 sketchup 的 SketchUp MCP 服务，请为此服务指定其他名称（例如 sketchup-node），以避免工具重复。

claude mcp add sketchup --scope user -e SKETCHUP_MCP_TIMEOUT=120 -- node C:/Tools/sketchup-mcp/server/index.mjs
claude mcp list

{
  "mcpServers": {
    "sketchup": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/sketchup-mcp/server/index.mjs"],
      "env": { "SKETCHUP_MCP_TIMEOUT": "120" }
    }
  }
}

{
  "servers": {
    "sketchup": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/sketchup-mcp/server/index.mjs"],
      "env": { "SKETCHUP_MCP_TIMEOUT": "120" }
    }
  }
}

{
  "mcpServers": {
    "sketchup": {
      "command": "node",
      "args": ["C:/Tools/sketchup-mcp/server/index.mjs"],
      "env": { "SKETCHUP_MCP_TIMEOUT": "120" }
    }
  }
}

[mcp_servers.sketchup]
command = "node"
args = ["C:/Tools/sketchup-mcp/server/index.mjs"]
tool_timeout_sec = 180

[mcp_servers.sketchup.env]
SKETCHUP_MCP_TIMEOUT = "120"

{
  "mcpServers": {
    "sketchup": {
      "command": "node",
      "args": ["C:/Tools/sketchup-mcp/server/index.mjs"],
      "env": { "SKETCHUP_MCP_TIMEOUT": "120" }
    }
  }
}

网页版 ChatGPT 无法启动本地程序；要使用它，必须通过公共 HTTPS 端点公开此服务。 不建议这样做：run_ruby 会在 SketchUp 中执行任意 Ruby 代码，而且桥接程序没有身份验证。 请改用 ChatGPT 桌面应用（Codex 模式）。

安全说明

• 仅限本地主机。 桥接服务监听 127.0.0.1，因此网络上的其他计算机无法连接。不过，此套接字没有身份验证：桥接服务运行期间，同一台计算机上的任何程序都可以发送命令。若要在当前会话中将其关闭，请使用 Extensions > SU MCP Bridge > Stop server（它会随 SketchUp 一起启动）。
• 保持启用审批。 Claude Desktop 会在每次调用工具前询问。不要对 run_ruby、delete_entities、undo、save_model、open_model、new_model、export_file、export_png 或 interior_takeoff 选择“始终允许”（导出工具，以及保存 CSV 时的工程量清单工具，都可能覆盖文件）。
• run_ruby 会在 SketchUp 中执行任意 Ruby 代码，使用你当前用户的权限，且没有时间限制。允许执行前请先阅读代码。无限循环会使 SketchUp 卡死，你只能从任务管理器中将其关闭，并会丢失未保存的更改。
• 每次编辑都是一个撤销步骤，因此可以按 Ctrl+Z 撤回错误结果，或让 Claude 撤销。
• 请使用项目副本进行操作，并在每次与 Claude 开始会话前保存一份副本。不指定路径的 save_model 会覆盖当前文件。
• 模型数据会发送给 Claude。 提出问题时，Claude 会读取模型信息（对象名称、数量、截图……），并将其发送到 Anthropic 的 Claude 服务进行处理。处理机密项目时，请遵守所在组织和客户的相关规定。

故障排除

日志文件（Extensions > SU MCP Bridge > Open log file）会记录命令名称、时间和错误消息，但不记录几何数据或完整代码。错误消息可能会引用 run_ruby 代码片段以及文件名或对象名称，因此分享日志前请先检查文件内容。

从源代码构建

cd mcpb
npm install
npm run build     # bundle with esbuild, build su_mcp.rbz from ../extension, validate + pack dist/sketchup-mcp-<version>.mcpb
npm test          # smoke test + unit tests against a mock bridge (no SketchUp needed)
npm run release   # build + unit tests + ../release/SketchUpMCP_v<version>/ and its .zip (PDF guides need Microsoft Edge)

• 4 处的版本号必须一致：mcpb/package.json、mcpb/manifest.json、extension/su_mcp/main.rb（VERSION）和 extension/su_mcp.rb（ext.version）。如果不一致，构建会停止。
• Ruby 桥接代码使用 Ruby 2.2 语法，以便在 SketchUp 2017 及更高版本中运行（不使用 &.、Array#sum、match? 等）。
• 不要更改 manifest.json 中的 name（sketchup-mcp）或 author.name：Claude Desktop 会将它们用作安装 ID，更改其中任意一项都会导致新版本作为第二个扩展安装，而不是更新现有扩展。
• node scripts/smoke-test.mjs --live 会针对正在运行的 SketchUp 调用只读工具。仅在可以安全操作的模型上使用。

仓库布局

extension/                   Ruby bridge (SU MCP Bridge)
  su_mcp.rb                  loader registered with SketchUp
  su_mcp/main.rb             TCP server on 127.0.0.1, commands, menu, status, log
mcpb/                        Node.js MCP server packaged as a Claude Desktop extension
  src/index.mjs              MCP tools, connection to the bridge, install_sketchup_bridge
  manifest.json              .mcpb manifest (tools, user settings: port, timeout)
  scripts/                   build.mjs, unit-test.mjs, smoke-test.mjs, release.mjs, versions.mjs, make-icon.mjs
  release-docs/en/           GUIDE.html, SAMPLE_PROMPTS.txt (English)
  release-docs/vi/           HUONG_DAN_SU_DUNG.html, CAU_LENH_MAU.txt (Vietnamese)
docs/images/                 README images (hero, demo GIF, social preview)
server.json                  entry for the official MCP Registry
.github/workflows/ci.yml     build + tests on Windows
.github/workflows/publish-mcp-registry.yml   publishes server.json to the MCP Registry (run by hand)

致谢

部分创意来自 zinin/sketchup-mcp2（MIT）：在 eval 中捕获所有异常、“可能已运行”提示、捕获后恢复相机，以及检查最低版本。本项目未复制任何代码。打包到服务中的第三方库及其许可证列于 THIRD_PARTY_NOTICES.txt，该文件由构建过程生成。

SketchUp 是 Trimble Inc. 的商标。Claude 是 Anthropic 的商标。本项目与这两家公司均无关联，也未获其认可。

许可证

本项目根据 MIT License 发布。版权所有 (c) 2026 Khuong Doan。