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. リリースから sh3d-mcp-plugin-1.2.0.sh3p をダウンロードします。

ステップ 2. インストールします。

macOS（最も簡単）：.sh3p ファイルをダブルクリックします。 Sweet Home 3D が起動し、プラグインを自動でインストールして、ダイアログで完了を知らせます。手動でファイルをコピーする必要はありません。Finder でファイルを開いたときに Sweet Home 3D が起動しない場合は、ファイルを右クリックして 「このアプリケーションで開く」→「Sweet Home 3D」 を選択します。 Sweet Home 3D が .sh3p 拡張子に関連付けられていれば、Windows と Linux でも同様にダブルクリックでインストールできます。

すべてのプラットフォーム（手動）：ファイルをプラグインフォルダーにコピーします。 フォルダーが存在しない場合は作成してください。

OS	プラグインフォルダー
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 サーバーが起動しない（ポートを開けない）

Sweet Home 3D の Mac App Store 版はサンドボックス化されており、com.apple.security.network.server エンタイトルメントが含まれていないため、リスニングソケットを開くことが許可されていません。プラグインはポート 9877 でリッスンするため、このビルドでは MCP サーバーを起動できません。

解決方法： Mac App Store 版ではなく、sweethome3d.com からサンドボックス化されていない Sweet Home 3D のビルド（スタンドアロンの「Java version」またはインストーラー）を使用してください。

認証

トークン認証はデフォルトではオフです。このモードでは、クライアントはAuthorizationヘッダーなしで接続し、プラグインはトークンファイルを作成せず、既存のトークンファイルも変更しません。このマシンで実行されるすべてのプログラムは、Sweet Home 3Dの権限でファイルを書き込むことも含め、MCPエンドポイントを通じて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を受け取ります。トークンを保存できない場合、認証の有効化は失敗し、トークン必須に設定されたサーバーは起動を拒否します。トークンの値がログやクライアントの設定ファイルに書き込まれることはありません。

認証が有効な場合は、以下のとおり、Claude CodeではheadersHelperまたは--headerを、Claude Desktopではmcp-remote --header-fileを設定してください。

Host/Originチェックは両方のモードで、/mcpと/healthに適用されます。サーバーは127.0.0.1のみでリッスンし、Hostが127.0.0.1:<port>またはlocalhost:<port>以外のリクエスト、あるいはOriginがhttp://127.0.0.1:<port> / http://localhost:<port>以外のリクエストを拒否します（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のパスです。お使いのOSに合わせて調整してください）。

{
  "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	2 点間に単一の壁を作成
create_walls	長方形の部屋を作成（接続された 4 枚の壁）
modify_wall	高さ、厚さ、色、弧、座標を変更
delete_wall	ID を指定して壁を削除
connect_walls	角を正しく描画できるよう 2 枚の壁を接続

部屋

コマンド	説明
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 を指定して 1 つ以上のオブジェクトを複製
group_furniture	複数の家具を 1 つのオブジェクトにグループ化
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、0 始まりの 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.1.0 以前、または Sweet Home 3D バージョン 5.3 より前のバージョンで保存されたファイルを load_home で読み込むには、Sweet Home 3D で開いて再保存する必要があります。 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 からのダウンロードに切り替えます。 3 つの Java3D JAR（j3dcore、j3dutils、vecmath）は lib/ に直接含まれています。

アーキテクチャ

このプラグインは、外部の実行時依存関係を持たない、単一の自己完結型コンポーネントです。

• plugin — エントリーポイント（SH3DMcpPlugin）、設定ダイアログ
• http — Streamable 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 General Public License v2.0 — 詳細は LICENSE をご覧ください。

このプラグインは、Sweet Home 3D Plugin API（GPL v2）および Java3D（BSD / JOGL ライセンス）を使用しています。