Sweethome3d MCP Server

甜蜜之家3D MCP插件

  

一个插件 甜蜜的家3D 其将MCP（模型上下文协议）服务器直接嵌入应用程序中。让Claude和其他人工智能助手通过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         │
└─────────────────────────────────────┘

截图

3D scene created via MCP

MCP Server Settings dialog

需求

注： Sweet Home 3D附带了捆绑的JRE。请确保它是Java 11+。由于以下原因，非常旧的SH3D版本（JRE 1.8的32位Windows安装程序）将无法加载插件 UnsupportedClassVersionError.

安装

步骤1。 下载最新 .sh3p 文件来自 发布.

步骤2。 将其复制到您的Sweet Home 3D插件文件夹：

步骤3。 重启《甜蜜家园3D》。MCP服务器在端口上自动启动 9877.

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

克劳德配置

添加到您的Claude桌面 claude_desktop_config.json:

{
  "mcpServers": {
    "sweethome3d": {
      "type": "http",
      "url": "http://localhost:9877/mcp"
    }
  }
}

对于Claude Code，创建 .mcp.json 在您的项目目录中：

{
  "mcpServers": {
    "sweethome3d": {
      "type": "http",
      "url": "http://localhost:9877/mcp"
    }
  }
}

该插件还内置了 “自动配置克劳德桌面” 按钮位于 工具→ MCP服务器。.. 自动写入此配置。

可用命令

12个类别的42个命令。

场景

墙

房间

家具

门窗

纹理和外观

3D形状

注释

相机

多级

渲染和导出

保存/加载

检查点（撤消时间线）

批次

坐标系

• 单位： 厘米 （500=5米）
• X轴：右，Y轴： 下 （屏幕坐标）
• 所有对象ID都是稳定的UUID——可以在多个调用中安全使用

从源头构建

先决条件： Java 11+、Maven 3.6+（或使用附带的 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.0.0.sh3p

为什么是设置脚本？ SweetHome3D.jar 是从git中排除的46 MB二进制文件。 该脚本首先检查您本地的Sweet Home 3D安装（最快，脱机工作）， 然后回到从SourceForge下载。 三个Java3D JAR(j3dcore, j3dutils, vecmath)包含在 lib/ 直接。

建筑

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

• plugin --入口点(SH3DMcpPlugin)，设置对话框
• http --流式HTTP MCP服务器（JSON-RPC 2.0，端口9877）
• command --42个命令处理程序，通过自动注册 CommandRegistry
• bridge -威胁安全的甜蜜家园3D API包装(HomeAccessor 通过EDT， CheckpointManager, ObjectResolver)
• protocol --手写JSON解析器（零外部依赖）
• config --插件设置，Claude Desktop自动配置器

看 建筑.md 用于完整的设计、ADR决策和序列图。

添加新命令

只需要一个类——注册表会自动拾取它：

public class MyCommandHandler implements CommandHandler, CommandDescriptor {

    @Override
    public Response execute(Request request, HomeAccessor accessor) {
        // All Home mutations must run on the Event Dispatch Thread:
        Object result = accessor.runOnEDT(() -> {
            Home home = accessor.getHome();
            // ... do something
            return "done";
        });
        return Response.success(result);
    }

    @Override
    public String getDescription() { return "Does something useful."; }

    @Override
    public Map getSchema() {
        return SchemaBuilder.object()
            .prop("name", "string", "Object name")
            .required("name")
            .build();
    }
}

然后在中注册 SH3DMcpPlugin.createCommandRegistry():

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

看 贡献.md 获取完整的开发指南。

许可证

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

此插件使用 甜蜜的家3D 插件API（GPL v2）和Java3D（BSD/JOGL许可证）。