sweethome3d-mcp-server

Sweet Home 3D MCP 插件

这是一个适用于 Sweet Home 3D 的插件，可直接在应用中嵌入 MCP（Model Context Protocol）服务。它让 Claude 和其他 AI 助手通过 HTTP 控制 Sweet Home 3D——创建墙体、摆放家具、渲染照片等，无需任何外部代理或独立服务进程。

Claude Desktop / Claude Code
         │  HTTP (JSON-RPC 2.0)
         ▼
┌─────────────────────────────────────┐
│  Sweet Home 3D  +  MCP Plugin       │
│  Built-in HTTP server on port 9877  │
│  http://127.0.0.1:9877/mcp         │
└─────────────────────────────────────┘

Claude Code 可直接连接到此端点。Claude Desktop 需要在中间使用一个小型本地桥接程序（mcp-remote）——请参阅Claude 配置。

截图

要求

要求	版本
Sweet Home 3D	7.x（已使用 7.5 测试）
Java（随 SH3D 附带或系统安装）	8 或更高版本
Node.js	当前 LTS 版本——仅 Claude Desktop 需要（用于运行 mcp-remote 桥接程序）

该插件可与 Sweet Home 3D 自带的 Java 8 运行时配合使用。构建插件需要 JDK 11+；运行插件则不需要。

安装

步骤 1。 从 Releases 下载 sh3d-mcp-plugin-1.2.0.sh3p。

步骤 2。 安装。

macOS（最简单）：双击 .sh3p 文件。 Sweet Home 3D 会启动并自动安装插件，然后通过对话框确认。无需手动复制。如果 Finder 无法使用 Sweet Home 3D 打开该文件，请右键单击并选择 打开方式 → Sweet Home 3D。在 Windows 和 Linux 上，只要 .sh3p 扩展名已关联到 Sweet Home 3D，双击操作也同样有效。

任何平台（手动）：将文件复制到插件文件夹中，如果文件夹不存在，请先创建：

操作系统	插件文件夹
Windows	%APPDATA%\eTeks\Sweet Home 3D\plugins\
macOS	~/Library/Application Support/eTeks/Sweet Home 3D/plugins/
Linux	~/.eteks/sweethome3d/plugins/

步骤 3。 重新启动 Sweet Home 3D。MCP 服务会自动在端口 9877 上启动。

可验证服务是否正在运行：工具 → MCP 服务... 会显示服务状态。

故障排除

macOS：MCP 服务无法启动（无法打开端口）

Mac App Store 版本的 Sweet Home 3D 处于沙盒环境中，且未包含 com.apple.security.network.server 权限，因此无法打开 监听套接字。由于插件会监听端口 9877，MCP 服务 无法在该版本下启动。

解决方法： 使用非沙盒版本的 Sweet Home 3D——从 sweethome3d.com 下载独立的“Java 版本”或安装程序，而不要使用 Mac App Store 版本。

身份验证

默认情况下，令牌身份验证处于关闭状态。在此模式下，客户端无需提供 Authorization 标头即可连接，插件不会创建令牌文件，也不会更改现有令牌文件。 此计算机上运行的任何程序都可以通过 MCP 端点控制 Sweet Home 3D，包括以 Sweet Home 3D 的权限写入文件。 如果此计算机由不受信任的程序或其他用户共用，请启用令牌身份验证。

如需要求身份验证，请在 Tools → MCP Server... 中选择 Require a token。更改会在下一个请求时生效，包括现有会话中的请求，无需重启服务。 该设置会保存为插件文件夹中 sh3d-mcp.properties 文件里的 sh3d.mcp.requireToken=true。 JVM 属性 -Dsh3d.mcp.requireToken=true|false 会覆盖该文件中的设置，并锁定复选框。 取消勾选此项即可再次允许无令牌连接；现有令牌文件会保留。

启用身份验证后，对 /mcp 的每个请求都必须携带 Authorization: Bearer <token>； 缺少令牌或令牌不正确时会返回 401。/health 无需令牌。 插件会在需要时生成一个随机令牌（32 字节，base64url），并将其存储在插件旁边的文件中，且仅你本人可读（POSIX 上为 0600，Windows 上使用仅限所有者的显式 ACL）：

文件	内容
sh3d-mcp.token	原始令牌
sh3d-mcp.token.headers	Authorization: Bearer <token>（供 mcp-remote --header-file 使用）

这两个文件都位于上文所述的插件文件夹中。Tools → MCP Server... 会显示令牌（经过遮盖），允许你复制令牌，并在启用身份验证时轮换令牌；使用旧令牌的客户端将收到 401。如果无法存储令牌，启用身份验证会失败；如果服务配置为要求令牌，则会拒绝启动。令牌值绝不会写入日志或客户端配置文件。

启用身份验证后，请按照下文所示，使用 headersHelper 或 --header 配置 Claude Code，使用 mcp-remote --header-file 配置 Claude Desktop。

两种模式都会进行 Host/Origin 检查，适用于 /mcp 和 /health。服务仅监听 127.0.0.1，并会拒绝（403）Host 不为 127.0.0.1:<port> 或 localhost:<port> 的请求，或携带非 http://127.0.0.1:<port> / http://localhost:<port> Origin 的请求（防范 DNS 重绑定和跨站攻击）。不会发送 CORS 标头。 Host 和 Origin 比较时不区分大小写；重复值或以逗号分隔的值会被拒绝。 在端口 80 上，也接受省略 :80 的相同地址。 请求正文大小限制为 5 MB（413）。

Claude 配置

请先启动 Sweet Home 3D：只有应用运行时，MCP 服务才会存在。

Claude Code（推荐）

在默认的无令牌模式下，将 .mcp.json.example 复制到项目目录中的 .mcp.json， 或者使用以下命令注册端点：

claude mcp add --transport http sweethome3d http://127.0.0.1:9877/mcp

启用令牌身份验证后，请使用以下 .mcp.json。headersHelper 会在每次连接时读取 令牌文件，因此令牌不会被复制到配置中，轮换令牌后也会自动获取新令牌（以下显示 macOS 路径；请根据你的操作系统调整）：

{
  "mcpServers": {
    "sweethome3d": {
      "type": "http",
      "url": "http://127.0.0.1:9877/mcp",
      "headersHelper": "printf '{\"Authorization\":\"Bearer %s\"}' \"$(cat \"$HOME/Library/Application Support/eTeks/Sweet Home 3D/plugins/sh3d-mcp.token\")\""
    }
  }
}

也可以使用静态标头（轮换令牌后必须更新）：

claude mcp add --transport http sweethome3d http://127.0.0.1:9877/mcp \
  --header "Authorization: Bearer <token>"

Claude Desktop

Claude Desktop 不会从 claude_desktop_config.json 加载 "type": "http" 条目——此类条目会被忽略。 它会将 MCP 服务作为本地命令启动，因此需要通过固定版本的 mcp-remote 桥接器访问插件（需要 Node.js）。 在默认的免令牌模式下，将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "sweethome3d": {
      "command": "npx",
      "args": ["-y", "[email protected]", "http://127.0.0.1:9877/mcp"]
    }
  }
}

启用令牌身份验证时，按如下所示添加 --header-file 和标头文件的绝对路径（此处显示 macOS 路径）。令牌会从该文件读取，不会出现在配置文件或进程命令行中：

{
  "mcpServers": {
    "sweethome3d": {
      "command": "npx",
      "args": [
        "-y", "[email protected]", "http://127.0.0.1:9877/mcp",
        "--header-file", "/Users/<you>/Library/Application Support/eTeks/Sweet Home 3D/plugins/sh3d-mcp.token.headers"
      ]
    }
  }
}

然后完全退出 Claude Desktop，再重新启动。

Tools → MCP Server... 中内置的 “Auto-configure Claude Desktop” 按钮会根据当前令牌模式写入此条目，仅在启用身份验证时包含标头文件路径（并保留先前配置的 .bak 副本）。Copy to Clipboard 按钮使用相同的模式。 更改令牌模式后，请重新配置客户端；轮换令牌后，请重启 Claude Desktop。

可用命令

14 个类别中共有 46 个命令。

场景

命令	描述
get_state	完整场景状态：墙体、家具、房间、摄像机、标签、楼层
clear_scene	移除场景中的所有对象

墙体

命令	描述
create_wall	在两点之间创建单面墙
create_walls	创建矩形房间（由 4 面相连的墙组成）
modify_wall	更改高度、厚度、颜色、弧度和坐标
delete_wall	按 ID 删除墙体
connect_walls	连接两面墙，以正确渲染墙角

房间

命令	描述
create_room_polygon	根据多边形点数组创建房间
modify_room	更改名称、地板／天花板颜色和可见性
delete_room	按 ID 删除房间

家具

命令	描述
list_categories	所有家具目录类别及其项目数量
list_furniture_catalog	浏览目录；按名称、类别或类型筛选
place_furniture	在场景中放置目录项目
modify_furniture	按 ID 移动、旋转、调整大小、重新着色家具；设置门／窗的开启弧度（sashPreset / sashes）
delete_furniture	按 ID 删除家具
duplicate_objects	按 ID 复制一个或多个对象
group_furniture	将多件家具组合成一个对象
ungroup_furniture	将组合拆分为单件家具

门和窗

命令	描述
place_door_or_window	从目录中选取门窗并放置到墙上（自动计算位置和角度）；可选使用 sashPreset / sashes 设置平面图中的开启弧度

纹理和外观

命令	描述
list_textures_catalog	浏览纹理目录；按名称或类别筛选
apply_texture	将目录纹理应用于墙面或房间表面
set_environment	地面／天空颜色、照明、墙体透明度、绘制模式

3D 形状

命令	描述
generate_shape	创建自定义 3D 几何体：基元（箱体、球体、圆柱体、圆锥体、楔体、拱门、楼梯、圆环、半球、管道）、拉伸、网格和 CSG 布尔运算（并集、差集、交集）

注释

命令	描述
add_label	在 2D 平面图上添加文本注释
modify_label	按 ID 更改标签文本、位置、角度、颜色、字体样式或 3D 放置方式
delete_label	按 ID 删除标签
add_dimension_line	添加带自动偏移的测量线
modify_dimension_line	按 ID 移动尺寸线端点或调整偏移
delete_dimension_line	按 ID 删除尺寸线

相机

命令	描述
set_camera	切换到顶部/观察者模式；设置位置、lookAt 点或 target 对象
store_camera	将当前视角保存为命名书签
get_cameras	列出所有已保存的相机视角

多楼层

命令	描述
add_level	添加新楼层
list_levels	列出所有楼层及其稳定的字符串 id、从零开始的 index 和当前选中状态
set_selected_level	切换当前活动楼层
delete_level	删除楼层及其所有对象

渲染与导出

命令	描述
render_photo	光线追踪 3D 渲染（Sunflow）；标准视图或俯视鸟瞰视图；内嵌 JPEG 或保存为 PNG
export_plan_image	将 2D 平面图导出为 PNG
export_svg	将 2D 平面图导出为 SVG
export_to_obj	将 3D 场景导出为 Wavefront OBJ（ZIP：OBJ + MTL + 纹理）

保存 / 加载

命令	描述
save_home	将场景保存到 .sh3d 文件
load_home	加载包含 Home.xml 的 .sh3d 文件，替换当前场景

检查点（撤销时间线）

命令	描述
checkpoint	保存内存快照，其数值 ID 稳定且永不复用（可选描述）
restore_checkpoint	从快照恢复（支持强制模式）
list_checkpoints	列出所有快照及当前撤销游标位置

批处理

命令	描述
batch_commands	在一个请求中执行多个命令

由插件 1.1.0 或更早版本，以及 Sweet Home 3D 5.3 之前的版本保存的文件， 必须先在 Sweet Home 3D 中重新打开并保存，load_home 才能读取。 请参阅 1.2.0 升级说明。

坐标系

• 单位：厘米（500 = 5 米）
• X 轴：向右，Y 轴：向下（屏幕坐标）
• 所有对象 ID 都是稳定的 UUID，可安全地用于多次调用

从源代码构建

**先决条件：**构建和测试需要 JDK 11+，Maven 3.9+（或使用随附的 mvnw 包装脚本）。

# 1. Clone
git clone https://github.com/grimashevich/sweethome3d-mcp-server.git
cd sweethome3d-mcp-server

# 2. Obtain SweetHome3D.jar (copies from your SH3D installation or downloads it)
./scripts/setup-dev.sh        # macOS / Linux / Git Bash on Windows
# scripts\setup-dev.bat       # Windows Command Prompt

# 3. Build
./mvnw clean package

# 4. Run tests
./mvnw test

# The plugin artifact is at:
# target/sh3d-mcp-plugin-1.2.0.sh3p

为什么需要设置脚本？ SweetHome3D.jar 是一个 46 MB 的二进制文件，未纳入 git。 脚本会先检查本地 Sweet Home 3D 安装（速度最快，可离线使用）， 然后再尝试从 SourceForge 下载。 三个 Java3D JAR（j3dcore、j3dutils、vecmath）已直接包含在 lib/ 中。

架构

该插件是一个独立的组件，没有外部运行时依赖：

• plugin — 入口点（SH3DMcpPlugin）、设置对话框
• http — 可流式传输的 HTTP MCP 服务（JSON-RPC 2.0，端口 9877）、RequestGuard 过滤器
• command — 注册表和接口；command.handler 中有 46 个处理器，command.shape 中有生成器，command.util 中有通用辅助工具
• bridge — 线程安全的 Sweet Home 3D API 封装（通过 EDT 调用 HomeAccessor、CheckpointManager、ObjectResolver）
• protocol — 手写的 JSON 解析器（零外部依赖）
• config — 插件设置、AuthTokenStore、Claude Desktop 自动配置器

完整设计、ADR 决策和时序图请参阅 ARCHITECTURE.md。

添加新命令

创建 src/main/java/com/sh3d/mcp/command/handler/MyCommandHandler.java：

package com.sh3d.mcp.command.handler;

import com.sh3d.mcp.bridge.HomeAccessor;
import com.sh3d.mcp.command.CommandDescriptor;
import com.sh3d.mcp.command.CommandHandler;
import com.sh3d.mcp.command.util.SchemaBuilder;
import com.sh3d.mcp.protocol.Request;
import com.sh3d.mcp.protocol.Response;

import java.util.LinkedHashMap;
import java.util.Map;

public class MyCommandHandler implements CommandHandler, CommandDescriptor {
    @Override
    public Response execute(Request request, HomeAccessor accessor) {
        String name = request.getString("name");
        if (name == null || name.trim().isEmpty()) {
            return Response.error("Missing or empty parameter: name");
        }

        Map<String, Object> data = accessor.runOnEDT(() -> {
            Map<String, Object> result = new LinkedHashMap<>();
            result.put("name", name);
            result.put("wallCount", accessor.getHome().getWalls().size());
            return result;
        });
        return Response.ok(data);
    }

    @Override
    public String getDescription() {
        return "Returns a name and the current wall count.";
    }

    @Override
    public Map<String, Object> getSchema() {
        return SchemaBuilder.create()
                .requiredString("name", "Name to include in the result (non-empty)")
                .build();
    }
}

然后导入处理器，并在 SH3DMcpPlugin.createCommandRegistry() 中注册：

registry.register("my_command", new MyCommandHandler());

完整开发指南请参阅 CONTRIBUTING.md。

贡献者

代码贡献：

• Daniel Whitston (@danwhitston) — 门窗放置和窗扇控制（PR #4，PR #5）。
• Rolfy N. Montufar (@rolfymontufar) — 尺寸线编辑和删除（PR #6）。
• Oskar Lindh (@Olindh) — 修复 HTTP 请求和住宅文件加载中的安全问题。
• @SharonSx — 标签编辑和删除（PR #14）。

感谢大家提交详尽的错误报告：

• @ikeoffiah — #9、#10、#11。
• @jacktwilliams — #13。
• @arkansas-coder — #7。

许可证

GNU 通用公共许可证 v2.0 — 详情请参阅 LICENSE。

此插件使用 Sweet Home 3D 插件 API（GPL v2）和 Java3D（BSD / JOGL 许可证）。