SketchupMCP - Sketchup Model Context Protocol 統合

元々は mhyrr/sketchup-mcp からフォークされたものです。 v0.0.1で新しいワイヤプロトコル（4バイトの長さプレフィックスフレーミング）を採用し、 モジュール式ハンドラーアーキテクチャ、拡張されたイントロスペクション/継手/エッジ操作ツール、 RubyおよびPython両側での完全なユニットテストカバレッジを備えて分岐しました。 sketchup-mcp2 としてPyPIに公開されています（元の sketchup-mcp パッケージはアップストリームです）。

SketchupMCPは、Model Context Protocol (MCP) を介してSketchupをClaude AIに接続し、ClaudeがSketchupを直接操作および制御できるようにします。この統合により、Sketchupでのプロンプト支援による3Dモデリング、シーン作成、操作が可能になります。

インスピレーションと構造を提供してくれた Blender MCP に感謝します。

機能

• 双方向通信: TCPソケット接続を介してClaude AIをSketchupに接続

• コンポーネント操作: Sketchup内のコンポーネントの作成、変更、削除、変換

• マテリアル制御: マテリアルや色の適用と変更

• シーン検査: 現在のSketchupシーンに関する詳細情報の取得

• 選択処理: 選択されたコンポーネントの取得と操作

• Rubyコード評価: 高度な操作のために、Sketchup内で任意のRubyコードを実行

Related MCP server: SketchupMCP

コンポーネント

システムは主に2つのコンポーネントで構成されています。

1. SketchUp拡張機能 (su_mcp/su_mcp/): Sketchup内でTCPサーバーを実行するモジュール式のRubyプラグイン (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] > [Start Server] に移動します

2. サーバーがデフォルトポート (9876) で起動します

3. ターミナルでMCPサーバーが実行されていることを確認してください

Claudeでの使用

Claudeの設定に以下を追加して、ClaudeがMCPサーバーを使用するように構成します。

    "mcpServers": {
        "sketchup": {
            "command": "uvx",
            "args": [
                "sketchup-mcp2"
            ]
        }
    }

これにより、PyPIの最新版 が取得されます。

接続が完了すると、Claudeは以下の機能を使用してSketchupと対話できます。

ツール

ジオメトリと変換:

• create_component — 指定された寸法 (mm) で立方体/円柱/円錐/球を作成

• delete_component — シーンからコンポーネントを削除

• transform_component — コンポーネントの移動/回転/拡大縮小 (平行移動はmm単位)

• set_material — コンポーネントに名前付きまたは16進数 (#rrggbb) の色を適用

• export_scene — skp/obj/dae/stl/png/jpg にエクスポート

ブール演算とエッジ操作:

• boolean_operation — 2つのソリッドに対する和/差/積

• chamfer_edge — グループ/コンポーネントのすべてのエッジを面取り (距離はmm単位)

• fillet_edge — すべてのエッジをフィレット（丸め） (半径はmm単位、セグメント数は設定可能)

継手:

• create_mortise_tenon, create_dovetail, create_finger_joint — 木工継手 (寸法はmm単位)

イントロスペクション:

• 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オブジェクトです

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

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 — パスに沿ったプロファイル」 — 周囲の土台（mauerlat）。

• 「一般的な落とし穴」 — Group#subtract の逆セマンティクスの注意点を含む。

トラブルシューティング

SketchUp not running or extension not started: ...

Python MCPサーバーがポート9876で接続を試みましたが、リッスンしているものが見つかりませんでした。 以下のいずれかを確認してください:

• SketchUpが実行されていない

• MCPプラグインがインストールされているが開始されていない — [プラグイン] → [MCP Server] → [Start] を開いてください。

このエラーの後もサーバーは生存し続けます。次のツール呼び出しで接続が再試行されます。