Skip to content
Back to search

sweethome3d-mcp-server

Sweet Home 3D plugin that embeds an MCP server — lets Claude control Sweet Home 3D over HTTP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/grimashevich--sweethome3d-mcp-server/badge.svg)](/listings/grimashevich--sweethome3d-mcp-server)

HTML

<a href="/listings/grimashevich--sweethome3d-mcp-server"><img src="/api/listings/grimashevich--sweethome3d-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Step 1.** Download the latest `.sh3p` file from [Releases](../../releases).

**Step 2.** Install it.

*macOS (easiest): double-click the `.sh3p` file.* Sweet Home 3D opens, installs the plugin itself and confirms with a dialog. Nothing to copy by hand. If Finder does not open the file with Sweet Home 3D, right-click it and choose **Open With → Sweet Home 3D**. Double-clicking works the same way on Windows and Linux wherever the `.sh3p` extension is associated with Sweet Home 3D.

*Any platform (manual): copy the file into the plugins folder*, creating the folder if it does not exist:

| OS | Plugins folder | |----|----------------| | Windows | `%APPDATA%\eTeks\Sweet Home 3D\plugins\` | | macOS | `~/Library/Application Support/eTeks/Sweet Home 3D/plugins/` | | Linux | `~/.sweethome3d/plugins/` |

**Step 3.** (Re)start Sweet Home 3D. The MCP server starts automatically on port `9877`.

> You can verify it is running: **Tools → MCP Server...** shows the server status.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 442 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Sweet Home 3D MCP Plugin
  2. [![License: GPL v2](https://img.shields.io/badge/License-GPL_v2-blue.svg)](LICENSE)
  3. [![Java 8+](https://img.shields.io/badge/Java-8%2B-orange.svg)](https://adoptium.net/)
  4. [![Sweet Home 3D 7.x](https://img.shields.io/badge/Sweet_Home_3D-7.x-green.svg)](https://www.sweethome3d.com/)
  5. A plugin for [Sweet Home 3D](https://www.sweethome3d.com/) that embeds an MCP (Model Context Protocol) server directly inside the application. Lets Claude and other AI assistants control Sweet Home 3D over HTTP — create walls, place furniture, render photos, and more — without any external proxy or separate server process.
  6. ```
  7. Claude Desktop / Claude Code
  8. │ HTTP (JSON-RPC 2.0)
  9. ▼
  10. ┌─────────────────────────────────────┐
  11. │ Sweet Home 3D + MCP Plugin │
  12. │ Built-in HTTP server on port 9877 │
  13. │ http://127.0.0.1:9877/mcp │
  14. └─────────────────────────────────────┘
  15. ```
  16. Claude Code connects to this endpoint directly. Claude Desktop needs a small local bridge (`mcp-remote`) in
  17. between — see [Claude Configuration](#claude-configuration).
  18. ## Screenshots
  19. ![3D scene created via MCP](docs/demo.jpg)
  20. ![MCP Server Settings dialog](docs/screenshot.jpg)
  21. ## Requirements
  22. | Requirement | Version |
  23. |-------------|---------|
  24. | [Sweet Home 3D](https://www.sweethome3d.com/download.jsp) | 7.x (tested with 7.5) |
  25. | Java (bundled with SH3D or system) | 8 or newer |
  26. | [Node.js](https://nodejs.org/) | current LTS — only for Claude Desktop (runs the `mcp-remote` bridge) |
  27. The plugin works with Sweet Home 3D's bundled Java 8 runtime. Building the plugin requires JDK 11+; running it does not.
  28. ## Installation
  29. **Step 1.** Download `sh3d-mcp-plugin-1.2.0.sh3p` from [Releases](../../releases).
  30. **Step 2.** Install it.
  31. *macOS (easiest): double-click the `.sh3p` file.* Sweet Home 3D opens, installs the
  32. plugin itself and confirms with a dialog. Nothing to copy by hand. If Finder does not
  33. open the file with Sweet Home 3D, right-click it and choose **Open With → Sweet Home 3D**.
  34. Double-clicking works the same way on Windows and Linux wherever the `.sh3p` extension
  35. is associated with Sweet Home 3D.
  36. *Any platform (manual): copy the file into the plugins folder*, creating the folder if
  37. it does not exist:
  38. | OS | Plugins folder |
  39. |----|----------------|
  40. | Windows | `%APPDATA%\eTeks\Sweet Home 3D\plugins\` |
  41. | macOS | `~/Library/Application Support/eTeks/Sweet Home 3D/plugins/` |
  42. | Linux | `~/.eteks/sweethome3d/plugins/` |
  43. **Step 3.** (Re)start Sweet Home 3D. The MCP server starts automatically on port `9877`.
  44. > You can verify it is running: **Tools → MCP Server...** shows the server status.
  45. ## Troubleshooting
  46. ### macOS: the MCP server won't start (cannot open port)
  47. The **Mac App Store** build of Sweet Home 3D is sandboxed and ships without the
  48. `com.apple.security.network.server` entitlement, so it is not allowed to open a
  49. listening socket. Because the plugin listens on port `9877`, the MCP server
  50. cannot start under that build.
  51. **Fix:** use a non-sandboxed build of Sweet Home 3D — the standalone "Java
  52. version" / installer from [sweethome3d.com](https://www.sweethome3d.com/)
  53. instead of the Mac App Store version.
  54. ## Authentication
  55. Token authentication is **off by default**. In this mode clients connect without an
  56. `Authorization` header, and the plugin creates no token files or changes to existing token files.
  57. **Any program running on this machine can control Sweet Home 3D through the MCP endpoint, including writing files with the permissions of Sweet Home 3D.**
  58. Enable token authentication if untrusted programs or other users share the machine.
  59. To require authentication, select **Require a token** in **Tools → MCP Server...**. The change takes
  60. effect on the next request, including requests in existing sessions, without restarting the server.
  61. The setting is saved as `sh3d.mcp.requireToken=true` in `sh3d-mcp.properties` in the plugins folder.
  62. The JVM property `-Dsh3d.mcp.requireToken=true|false` overrides that file and locks the checkbox.
  63. Clear the checkbox to allow connections without a token again; existing token files are left in place.
  64. When authentication is enabled, every request to `/mcp` must carry `Authorization: Bearer <token>`;
  65. a missing or incorrect token returns `401`. `/health` does not require a token.
  66. The plugin generates a random token (32 bytes, base64url) when needed and stores it next to the
  67. plugin, readable only by you (`0600` on POSIX, an explicit owner-only ACL on Windows):
  68. | File | Contents |
  69. |------|----------|
  70. | `sh3d-mcp.token` | the raw token |
  71. | `sh3d-mcp.token.headers` | `Authorization: Bearer <token>` (for `mcp-remote --header-file`) |
  72. Both live in the plugins folder listed above. **Tools → MCP Server...** shows the token (masked),
  73. lets you copy it, and lets you **rotate** it when authentication is enabled; clients using the
  74. old token then get `401`. If token storage is unavailable, enabling authentication fails, and a
  75. server configured to require a token refuses to start. Token values are never written to logs or
  76. client configuration files.
  77. With authentication enabled, configure Claude Code using `headersHelper` or `--header`, and
  78. Claude Desktop using `mcp-remote --header-file`, as shown below.
  79. **Host/Origin checks apply in both modes**, to `/mcp` and `/health`. The server listens only on
  80. `127.0.0.1` and rejects (`403`) any request whose `Host` is not `127.0.0.1:<port>` or
  81. `localhost:<port>`, or that carries an `Origin` other than `http://127.0.0.1:<port>` /
  82. `http://localhost:<port>` (DNS-rebinding and cross-site protection). No CORS headers are sent.
  83. Host and Origin comparisons ignore case; repeated or comma-separated values are rejected.
  84. On port 80, the same addresses without `:80` are also accepted.
  85. Request bodies are limited to 5 MB (`413`).
  86. ## Claude Configuration
  87. Start Sweet Home 3D first: the MCP server exists only while the application is running.
  88. ### Claude Code (recommended)
  89. With the default token-free mode, copy `.mcp.json.example` to `.mcp.json` in your project directory,
  90. or register the endpoint with:
  91. ```bash
  92. claude mcp add --transport http sweethome3d http://127.0.0.1:9877/mcp
  93. ```
  94. **When token authentication is enabled**, use the following `.mcp.json`. `headersHelper` reads the
  95. token file on every connect, so the token is never copied into the config and a rotation is picked
  96. up automatically (macOS path shown; adjust for your OS):
  97. ```json
  98. {
  99. "mcpServers": {
  100. "sweethome3d": {
  101. "type": "http",
  102. "url": "http://127.0.0.1:9877/mcp",
  103. "headersHelper": "printf '{\"Authorization\":\"Bearer %s\"}' \"$(cat \"$HOME/Library/Application Support/eTeks/Sweet Home 3D/plugins/sh3d-mcp.token\")\""
  104. }
  105. }
  106. }
  107. ```
  108. Alternatively, with a static header (you must update it after a rotation):
  109. ```bash
  110. claude mcp add --transport http sweethome3d http://127.0.0.1:9877/mcp \
  111. --header "Authorization: Bearer <token>"
  112. ```
  113. ### Claude Desktop
  114. Claude Desktop does not load `"type": "http"` entries from `claude_desktop_config.json` — such an entry is ignored.
  115. It starts MCP servers as local commands, so the plugin is reached through a pinned
  116. [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge (requires [Node.js](https://nodejs.org/)).
  117. In the default token-free mode, add this to `claude_desktop_config.json`:
  118. ```json
  119. {
  120. "mcpServers": {
  121. "sweethome3d": {
  122. "command": "npx",
  123. "args": ["-y", "mcp-remote@0.14.3", "http://127.0.0.1:9877/mcp"]
  124. }
  125. }
  126. }
  127. ```
  128. **When token authentication is enabled**, add `--header-file` and the absolute path to the headers
  129. file as below (macOS path shown). The token is read from that file and never appears in the config
  130. or on the process command line:
  131. ```json
  132. {
  133. "mcpServers": {
  134. "sweethome3d": {
  135. "command": "npx",
  136. "args": [
  137. "-y", "mcp-remote@0.14.3", "http://127.0.0.1:9877/mcp",
  138. "--header-file", "/Users/<you>/Library/Application Support/eTeks/Sweet Home 3D/plugins/sh3d-mcp.token.headers"
  139. ]
  140. }
  141. }
  142. }
  143. ```
  144. Then quit Claude Desktop completely and start it again.
  145. > The built-in **"Auto-configure Claude Desktop"** button in **Tools → MCP Server...** writes this
  146. > entry for the current token mode, including the headers path only when authentication is enabled
  147. > (and keeps a `.bak` copy of the previous config). The **Copy to Clipboard** button uses the same mode.
  148. > Configure the client again after changing token mode, and restart Claude Desktop after rotating the token.
  149. ## Available Commands
  150. 46 commands across 14 categories.
  151. ### Scene
  152. | Command | Description |
  153. |---------|-------------|
  154. | `get_state` | Full scene state: walls, furniture, rooms, camera, labels, levels |
  155. | `clear_scene` | Remove all objects from the scene |
  156. ### Walls
  157. | Command | Description |
  158. |---------|-------------|
  159. | `create_wall` | Single wall between two points |
  160. | `create_walls` | Rectangular room (4 connected walls) |
  161. | `modify_wall` | Change height, thickness, color, arc, coordinates |
  162. | `delete_wall` | Delete wall by ID |
  163. | `connect_walls` | Connect two walls for correct corner rendering |
  164. ### Rooms
  165. | Command | Description |
  166. |---------|-------------|
  167. | `create_room_polygon` | Room from an array of polygon points |
  168. | `modify_room` | Change name, floor/ceiling color, visibility |
  169. | `delete_room` | Delete room by ID |
  170. ### Furniture
  171. | Command | Description |
  172. |---------|-------------|
  173. | `list_categories` | All furniture catalog categories with item counts |
  174. | `list_furniture_catalog` | Browse catalog; filter by name, category, or type |
  175. | `place_furniture` | Place a catalog item in the scene |
  176. | `modify_furniture` | Move, rotate, resize, recolor furniture by ID; set door/window swing arcs (`sashPreset` / `sashes`) |
  177. | `delete_furniture` | Delete furniture by ID |
  178. | `duplicate_objects` | Duplicate one or more objects by ID |
  179. | `group_furniture` | Group multiple pieces into one object |
  180. | `ungroup_furniture` | Split a group back into individual pieces |
  181. ### Doors & Windows
  182. | Command | Description |
  183. |---------|-------------|
  184. | `place_door_or_window` | Place from catalog into a wall (auto-computes position and angle); optional `sashPreset` / `sashes` for the plan's swing arc |
  185. ### Textures & Appearance
  186. | Command | Description |
  187. |---------|-------------|
  188. | `list_textures_catalog` | Browse texture catalog; filter by name or category |
  189. | `apply_texture` | Apply catalog texture to wall side or room surface |
  190. | `set_environment` | Ground/sky colors, lighting, wall transparency, drawing mode |
  191. ### 3D Shapes
  192. | Command | Description |
  193. |---------|-------------|
  194. | `generate_shape` | Create custom 3D geometry: primitives (box, sphere, cylinder, cone, wedge, arch, stairs, torus, hemisphere, pipe), extrude, mesh, and CSG boolean operations (union, subtract, intersect) |
  195. ### Annotations
  196. | Command | Description |
  197. |---------|-------------|
  198. | `add_label` | Text annotation on the 2D floor plan |
  199. | `modify_label` | Change a label's text, position, angle, colors, font style or 3D placement by ID |
  200. | `delete_label` | Delete label by ID |
  201. | `add_dimension_line` | Measurement line with auto-offset |
  202. | `modify_dimension_line` | Move a dimension line's endpoints or offset by ID |
  203. | `delete_dimension_line` | Delete dimension line by ID |
  204. ### Camera
  205. | Command | Description |
  206. |---------|-------------|
  207. | `set_camera` | Switch to top/observer mode; set position, `lookAt` point, or `target` object |
  208. | `store_camera` | Save the current viewpoint as a named bookmark |
  209. | `get_cameras` | List all saved camera viewpoints |
  210. ### Multi-level
  211. | Command | Description |
  212. |---------|-------------|
  213. | `add_level` | Add a new level (floor/storey) |
  214. | `list_levels` | List all levels with stable string `id`, zero-based `index`, and current selection |
  215. | `set_selected_level` | Switch the active level |
  216. | `delete_level` | Delete a level and all its objects |
  217. ### Rendering & Export
  218. | Command | Description |
  219. |---------|-------------|
  220. | `render_photo` | Ray-traced 3D render (Sunflow); standard or overhead bird's-eye view; inline JPEG or saved PNG |
  221. | `export_plan_image` | 2D floor plan as PNG |
  222. | `export_svg` | 2D floor plan as SVG |
  223. | `export_to_obj` | 3D scene as Wavefront OBJ (ZIP: OBJ + MTL + textures) |
  224. ### Save / Load
  225. | Command | Description |
  226. |---------|-------------|
  227. | `save_home` | Save the scene to a `.sh3d` file |
  228. | `load_home` | Load a `.sh3d` file containing `Home.xml`, replacing the current scene |
  229. ### Checkpoints (undo timeline)
  230. | Command | Description |
  231. |---------|-------------|
  232. | `checkpoint` | Save an in-memory snapshot with a stable, never-reused numeric ID (optional description) |
  233. | `restore_checkpoint` | Restore from a snapshot (supports force mode) |
  234. | `list_checkpoints` | List all snapshots with the current undo cursor position |
  235. ### Batch
  236. | Command | Description |
  237. |---------|-------------|
  238. | `batch_commands` | Execute multiple commands in one request |
  239. Files saved by plugin 1.1.0 or earlier, and by Sweet Home 3D versions before 5.3,
  240. must be opened and saved again in Sweet Home 3D before `load_home` can read them.
  241. See the [1.2.0 upgrade notes](CHANGELOG.md#upgrade-notes).
  242. ## Coordinate System
  243. - Units: **centimeters** (500 = 5 meters)
  244. - X axis: right, Y axis: **down** (screen coordinates)
  245. - All object IDs are stable UUIDs — safe to use across multiple calls
  246. ## Building from Source
  247. **Prerequisites:** JDK 11+ for building and tests, Maven 3.9+ (or use the included `mvnw` wrapper).
  248. ```bash
  249. # 1. Clone
  250. git clone https://github.com/grimashevich/sweethome3d-mcp-server.git
  251. cd sweethome3d-mcp-server
  252. # 2. Obtain SweetHome3D.jar (copies from your SH3D installation or downloads it)
  253. ./scripts/setup-dev.sh # macOS / Linux / Git Bash on Windows
  254. # scripts\setup-dev.bat # Windows Command Prompt
  255. # 3. Build
  256. ./mvnw clean package
  257. # 4. Run tests
  258. ./mvnw test
  259. # The plugin artifact is at:
  260. # target/sh3d-mcp-plugin-1.2.0.sh3p
  261. ```
  262. > **Why the setup script?** `SweetHome3D.jar` is a 46 MB binary excluded from git.
  263. > The script first checks your local Sweet Home 3D installation (fastest, works offline),
  264. > then falls back to downloading from SourceForge.
  265. > The three Java3D JARs (`j3dcore`, `j3dutils`, `vecmath`) are included in `lib/` directly.
  266. ## Architecture
  267. The plugin is a single self-contained component with no external runtime dependencies:
  268. - **`plugin`** — Entry point (`SH3DMcpPlugin`), settings dialog
  269. - **`http`** — Streamable HTTP MCP server (JSON-RPC 2.0, port 9877), `RequestGuard` filter
  270. - **`command`** — registry and interfaces; 46 handlers in `command.handler`, generators in `command.shape`, shared helpers in `command.util`
  271. - **`bridge`** — Thread-safe Sweet Home 3D API wrapper (`HomeAccessor` via EDT, `CheckpointManager`, `ObjectResolver`)
  272. - **`protocol`** — Hand-written JSON parser (zero external dependencies)
  273. - **`config`** — Plugin settings, `AuthTokenStore`, Claude Desktop auto-configurator
  274. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design, ADR decisions, and sequence diagrams.
  275. ## Adding a New Command
  276. Create `src/main/java/com/sh3d/mcp/command/handler/MyCommandHandler.java`:
  277. ```java
  278. package com.sh3d.mcp.command.handler;
  279. import com.sh3d.mcp.bridge.HomeAccessor;
  280. import com.sh3d.mcp.command.CommandDescriptor;
  281. import com.sh3d.mcp.command.CommandHandler;
  282. import com.sh3d.mcp.command.util.SchemaBuilder;
  283. import com.sh3d.mcp.protocol.Request;
  284. import com.sh3d.mcp.protocol.Response;
  285. import java.util.LinkedHashMap;
  286. import java.util.Map;
  287. public class MyCommandHandler implements CommandHandler, CommandDescriptor {
  288. @Override
  289. public Response execute(Request request, HomeAccessor accessor) {
  290. String name = request.getString("name");
  291. if (name == null || name.trim().isEmpty()) {
  292. return Response.error("Missing or empty parameter: name");
  293. }
  294. Map<String, Object> data = accessor.runOnEDT(() -> {
  295. Map<String, Object> result = new LinkedHashMap<>();
  296. result.put("name", name);
  297. result.put("wallCount", accessor.getHome().getWalls().size());
  298. return result;
  299. });
  300. return Response.ok(data);
  301. }
  302. @Override
  303. public String getDescription() {
  304. return "Returns a name and the current wall count.";
  305. }
  306. @Override
  307. public Map<String, Object> getSchema() {
  308. return SchemaBuilder.create()
  309. .requiredString("name", "Name to include in the result (non-empty)")
  310. .build();
  311. }
  312. }
  313. ```
  314. Then import the handler and register it in `SH3DMcpPlugin.createCommandRegistry()`:
  315. ```java
  316. registry.register("my_command", new MyCommandHandler());
  317. ```
  318. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
  319. ## Contributors
  320. Code contributions:
  321. - Daniel Whitston ([@danwhitston](https://github.com/danwhitston)) — door/window placement and sash controls ([PR #4](../../pull/4), [PR #5](../../pull/5)).
  322. - Rolfy N. Montufar ([@rolfymontufar](https://github.com/rolfymontufar)) — dimension line editing and deletion ([PR #6](../../pull/6)).
  323. - Oskar Lindh ([@Olindh](https://github.com/Olindh)) — security fixes for HTTP requests and home-file loading.
  324. - [@SharonSx](https://github.com/SharonSx) — label editing and deletion ([PR #14](../../pull/14)).
  325. Thank you for detailed bug reports:
  326. - [@ikeoffiah](https://github.com/ikeoffiah) — [#9](../../issues/9), [#10](../../issues/10), [#11](../../issues/11).
  327. - [@jacktwilliams](https://github.com/jacktwilliams) — [#13](../../issues/13).
  328. - [@arkansas-coder](https://github.com/arkansas-coder) — [#7](../../issues/7).
  329. ## License
  330. GNU General Public License v2.0 — see [LICENSE](LICENSE) for details.
  331. This plugin uses the [Sweet Home 3D](https://www.sweethome3d.com/) Plugin API (GPL v2) and Java3D (BSD / JOGL license).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.