OpenSCAD MCP Server

OpenSCAD MCP サーバー

OpenSCAD のソースまたは明示的なプリミティブ寸法から、編集可能な SCAD、STL ジオメトリ、4 枚の PNG プレビューを生成するローカル MCP サーバーです。接続されたアシスタントは複雑な設計の SCAD を作成でき、このサーバーはインストール済みの OpenSCAD 実行ファイルでコンパイルとレンダリングを行います。

**ステータス：**サポート対象の実装は src/openscad_mcp にあります。以前の画像生成、CUDA による再構築、リモート処理、プリンター関連のコードは legacy/ にアーカイブされています。未完成であり、インストールされるサーバーには含まれません。監査結果とマシンテスト結果を参照してください。

インストール

Python 3.11 以降と OpenSCAD が必要です。API キー、CUDA、Open3D、個別の画像レンダラーは不要です。

公式ダウンロードページから OpenSCAD をインストールしてください。macOS では、現在のネイティブ Apple Silicon／Intel ビルドを次のコマンドでインストールできます。

brew install --cask openscad@snapshot
openscad --version

Debian／Ubuntu では、sudo apt-get install openscad でディストリビューションのパッケージをインストールできます。Linux で PNG をレンダリングするには X ディスプレイが必要な場合があります。ヘッドレスマシンでは、サーバーやテストを xvfb-run -a で実行してください。Windows では、OPENSCAD_EXECUTABLE に openscad.exe の絶対パスを設定できます。

git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git
cd OpenSCAD-MCP-Server
uv sync --locked
uv run openscad-mcp --help

または、仮想環境に python -m pip install . でインストールし、openscad-mcp を実行してください。requirements.txt は同じパッケージをインストールします。uv.lock はテスト済みの依存関係の解決結果を固定します。プロジェクトのメタデータでは、互換性のある更新が許可されています。

シンボリックリンクを作成できない外部ファイルシステムでは、環境を内部ディスクに置いてください。

export UV_PROJECT_ENVIRONMENT="$HOME/.cache/openscad-mcp-venv"
uv sync --locked

Docker と Jetson

ヘッドレスの stdio イメージは、ルートの Dockerfile から利用できます。ビルドコマンド、MCP クライアントの設定、モデルの永続ストレージ、Glama への掲載要件については、Docker のセットアップと検証を参照してください。このイメージに GPU は不要です。

issue #19 のハードウェアに関する質問については、Jetson Orin Nano と CUDAを参照してください。サポート対象のサーバーは CUDA を使用しません。この Docker サポートによって、アーカイブされた再構築プロトタイプが復元されることもありません。

MCP クライアントの接続

デフォルトは stdio です。絶対パスを指定してサーバープロセスを起動するように、クライアントを設定してください。

{
  "mcpServers": {
    "openscad": {
      "command": "/absolute/path/to/venv/bin/openscad-mcp",
      "args": ["--output-dir", "/absolute/path/to/models"]
    }
  }
}

Streamable HTTP に対応するクライアントの場合：

uv run openscad-mcp --transport http --port 8000

MCP エンドポイントは http://127.0.0.1:8000/mcp です。/ はサーバー情報を表示し、/health は OpenSCAD のバージョンとプリミティブのデフォルト値を返します。HTTP ではプレビューページとダウンロードも提供されます。stdio モードでは、返された絶対ファイルパスまたは get_model_preview を使用してください。HTTP リスナーはありません。

ツール

ツール	用途
get_capabilities	OpenSCAD のバージョンと、デフォルトパラメーターを含むサポート対象のプリミティブ
create_3d_model	model_type と parameters、または簡単な説明を使ってプリミティブを作成します
create_model_from_scad	信頼できる scad_code をコンパイルして、カスタム 3D モデルを作成します
modify_3d_model	プリミティブのパラメーターを変更するか、モデルの scad_code を置き換えます
get_model	保存済みモデルと、そのアーティファクトのパスを読み取ります
get_model_source	Docker 内を含め、保存済みの SCAD ソースとリビジョンを読み取ります
get_model_preview	MCP の画像コンテンツとして PNG 画像を返します
export_model	scad、stl、csg、または 3mf にエクスポートします

create_3d_model の引数の例：

{
  "model_type": "box",
  "parameters": {"width": 40, "depth": 30, "height": 20, "thickness": 2}
}

寸法の単位はミリメートルです。サポートされているタイプは、cube（直方体も含む）、sphere、cylinder、box（中空の開いた箱）、rounded_box（ソリッド）、tube、cone、torus、prism（直角三角形の断面）、hexagonal_prism、text です。各タイプの正確なパラメーター名については、get_capabilities を呼び出してください。トーラスでは、チューブの中心までの半径（major_radius）とチューブの半径（minor_radius）を指定します。

任意の説明パーサーは、hollow box width 40 mm depth 30 mm height 20 mm thickness 2 mm や cube 2 cm wide 1 inch high のような、名前付きの寸法を認識します。mm、cm、m、インチに対応しています。単位を省略した場合は mm として扱われます。これは小規模なパーサーであり、汎用の自然言語モデルではありません。指定されていない寸法には、返されたデフォルト値が使われます。正確さが必要な場合は、明示的なパラメーターを指定してください。任意のオブジェクトを作るには、アシスタントに自己完結型の SCAD を記述させ、create_model_from_scad を呼び出してください。

{
  "scad_code": "difference() { cube([40,30,8]); translate([20,15,-1]) cylinder(h=10,r=5,$fn=48); }",
  "description": "Mounting plate with a through hole"
}

プリミティブを変更するには：

{"model_id": "ID_FROM_CREATION", "parameters": {"height": 25}}

カスタムモデルの場合は、モデル ID を指定して get_model_source を呼び出し、scad_code と revision を MCP 経由で直接取得します。返されたソースを編集し、新しい scad_code と、読み取ったリビジョンを設定した expected_revision を指定して modify_3d_model を呼び出します。ソースの読み取りにサーバーのファイルシステムへのアクセスは必要ありません。

同じ任意のリビジョンチェックは、プリミティブのパラメーター編集にも使用できます：

{
  "model_id": "ID_FROM_CREATION",
  "parameters": {"height": 25},
  "expected_revision": "REVISION_FROM_GET_MODEL"
}

別の編集がすでにコミットされている場合、レンダリングやファイルの変更より前に操作は失敗します。MCP はツールエラーを報告し、HTTP /tool_call API は current_revision とともに 409 を返します。最新のソースまたはパラメーターを読み取り、途中で行われた変更を反映してから再試行してください。expected_revision を省略すると、従来どおり無条件で編集されます。

編集可能なソースパラメーターが保持されるのは SCAD のみです。CSG は評価済みのジオメトリツリーです。STL と 3MF はメッシュであり、設計のパラメトリックな関係は保持されません。AMF（現在の OpenSCAD ビルドでは削除済み）、STEP、OBJ、2D エクスポート、画像からの再構成、印刷には対応していません。

HTTP スモークテスト

HTTP サーバーを起動した状態で：

curl --fail http://127.0.0.1:8000/tool_call \
  -H 'Content-Type: application/json' \
  -d '{"tool_name":"create_3d_model","tool_params":{"model_type":"box","parameters":{"width":40,"depth":30,"height":20,"thickness":2}}}'

返された preview_url を同じサーバー上で開いてください。/download/MODEL_ID?format=stl または ?format=scad をダウンロードします。/tool_call は便利な JSON API であり、/mcp で提供される実際の MCP プロトコルとは別のものです。この API で画像を取得するには、/preview/VIEW/MODEL_ID を使用します。

動作と制限

• 生成に成功するのは、実際の STL と 4 枚すべての PNG が生成された場合のみです。レンダラーの失敗、出力が空の場合、OpenSCAD の警告やエラーは失敗として報告されます。代替のジオメトリやプレビューは使用されません。
• 編集では新しいリビジョンが作成され、レンダリングの成功後にのみマニフェストが更新されます。以前のリビジョンはディスク上に残ります。モデルはサーバーを再起動しても保持されます。
• デフォルトの保存先は ~/.local/share/openscad-mcp/models です。--output-dir または OPENSCAD_OUTPUT_DIR で変更できます。各レンダリングのサブプロセスには 120 秒のタイムアウトが設定されており、--timeout で変更できます。モデルの生成には 5 つのサブプロセスが必要なため、リクエスト全体にはさらに時間がかかる場合があります。
• 出力ディレクトリごとに 1 つのサーバープロセスを実行してください。レンダリングと編集は直列に処理されます。ディスクの自動クリーンアップ、分散ジョブキュー、複数プロセス間のストア調整機能はありません。
• これは信頼できる環境で使用するローカルツールです。カスタム SCAD は、OpenSCAD の import、include、use を含め、現在のユーザーのファイルアクセス権限で実行されます。サンドボックス化はされていません。HTTP はループバックにバインドされ、ローカル以外の Host／Origin ヘッダーを拒否します。認証機能や、インターネット／LAN への公開はサポートされていません。
• macOS arm64 と、Xvfb を使用する Ubuntu 24.04 CI でローカルテスト済みです。Windows およびその他のプラットフォーム／ディスプレイの組み合わせでは検証されていません。ハードウェアプリンターやリモート GPU は使用していません。

開発と検証

uv sync --locked --group dev
uv run ruff check src/openscad_mcp tests scripts
uv run ruff format --check src/openscad_mcp tests scripts
uv run pytest -q

すべてのテストを実行するには OpenSCAD が必要です。利用できない場合、テストは失敗します。テストでは、実際の stdio および HTTP サーバープロセスを起動し、公式 MCP クライアントを使用して、エクスポートデータのダウンロード、PNG のデコード、メッシュのトポロジー／寸法／体積の検査、永続化と編集失敗のテスト、無効なリクエストの検証を行います。uv run pytest -m 'not integration' で実行できるのはユニットテストのみであり、エンドツーエンドの正しさは確認できません。

ライセンス

MIT。著作権は Jack Hacksman に帰属します（2026 年）。