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

组件

该系统由两个主要组件组成：

1. SketchUp 扩展 (su_mcp/su_mcp/)：一个模块化的 Ruby 插件，在 SketchUp 内部运行 TCP 服务器 (core/, handlers/, helpers/)。

2. 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 扩展

1. 下载或构建最新的 .rbz 文件

2. 在 Sketchup 中，转到“窗口” > “扩展程序管理器”

3. 点击“安装扩展程序”并选择下载的 .rbz 文件

4. 重启 Sketchup

使用方法

启动连接

1. 在 Sketchup 中，转到“扩展程序” > “SketchupMCP” > “启动服务器”

2. 服务器将在默认端口 (9876) 上启动

3. 确保 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” → “启动”。

服务器在此错误后保持活动状态；下一次工具调用将重试连接。