build123d MCP

build123d-mcp

AI に CAD を見せましょう。

build123d-mcp は、単体で動作するチャットボットや CAD プログラムではありません。AI／LLM アプリが MCP 経由で利用できる CAD ツールボックスです。

Claude、Cursor、VS Code、Continue、Cline、Codex CLI などの LLM アプリと組み合わせると、アシスタントは build123d-mcp を使って build123d の CAD モデルを作成し、プレビューをレンダリングし、ジオメトリを測定し、間違いを修正し、STEP、STL、SVG、DXF などのファイルをエクスポートできます。CAD スクリプト全体を見当もつかないまま作成するのではなく、アシスタントはパーツを少しずつ作成し、その都度結果を確認できます。

2026 年 6 月、公開されている CADGenBench のリーダーボードでは、build123d-mcp を使用することで、同じモデルのスコアが 0.360 から 0.457 に、CAD の有効率が 88% から 100% に向上しました。

環境を選ぶ

ほとんどのユーザーには、ローカル MCP サーバーのセットアップがおすすめです。

• ご自身のマシンで Claude、Cursor、VS Code、Continue、Cline、または Codex CLI を使用します。
• AI アプリが build123d-mcp をローカルのサブプロセスとして起動します。
• このリポジトリをクローンする必要はありません。

ブラウザーだけで試したい場合や、Copilot Chat、Python、uv、CAD の依存関係がすでにインストールされた開発用ワークスペースをすぐに使いたい場合は、代わりに GitHub Codespaces を利用してください。

HTTP モードは、MCP サーバーを自分でホストする高度なデプロイにのみ使用してください。

クイックスタート

必要なもの：

• uv
• MCP に対応した AI／LLM アプリ（Claude Code、Claude Desktop、Cursor、VS Code、Continue、Cline、Codex CLI など）

通常の利用では、リポジトリをクローンする必要はありません。まず、パッケージを起動できることを確認します。

uv tool run --python 3.12 build123d-mcp@latest --version

次に、同じコマンドを AI アプリの MCP 設定に追加します。共通部分は次のとおりです。

command: uv
args:    ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]

Python 3.11、3.12、3.13、3.14 に対応しています。例では無難な既定値として 3.12 を使用しています。まだインストールされていない場合は、uv でダウンロードできます。

AI アプリに接続する

構成要素は次のとおりです。

• LLM アプリは、アシスタントとチャットする場所です。
• MCP は、アシスタントがツールを呼び出すための接続です。
• build123d-mcp は、アシスタントが呼び出す CAD ツールサーバーです。

通常、サーバーは stdio 経由で実行されます。CAD ツールが必要になると、AI アプリがローカルのサブプロセスとして起動します。

Claude Code

プロジェクトの .mcp.json、またはグローバルに使用する場合は ~/.claude/mcp.json に以下を追加します。

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

編集後、Claude Code を再起動してください。

Claude Desktop

macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

保存後、Claude Desktop を再起動してください。

Cursor

Settings -> MCP を開いて新しいサーバーエントリを追加するか、 ~/.cursor/mcp.json を編集します。

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

VS Code、Continue、Cline、Codex CLI

AI アプリや拡張機能が読み込む MCP 設定で、同じコマンドと引数を使用します。正確なファイル名はアプリによって異なりますが、サーバーコマンドは同じです。

command: uv
args:    ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]

VS Code での GitHub Copilot の MCP サポート向けに、このリポジトリには開発用チェックアウトおよび Codespaces 用の .vscode/mcp.json が含まれています。別のワークスペースの場合、設定は次のようになります。

{
  "servers": {
    "build123d-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp@latest"]
    }
  }
}

最初のテスト用プロンプト

AI アプリをサーバーに接続したら、アシスタントに具体的なことを尋ねます。

Use build123d-mcp to make a 60 mm x 40 mm x 6 mm mounting plate with two
5 mm through holes 40 mm apart. Render it, measure it, then export STEP and STL.

効果的な作業サイクルは次のとおりです。

1. 一度に 1 つの機能を作成します。
2. 重要な手順の後にレンダリングまたは計測します。
3. エクスポート前に検証します。
4. 最終的なパーツをエクスポートします。

問題が発生した場合は、アシスタントに last_error を調べてスクリプトを修正し、次はより小さな手順を試すよう依頼します。

インポートしたパーツの編集

STEP をインポートして有効なベースラインを確立した後、find_candidates(kind="hole", qualifiers='{"axis":"Z","side":"+X"}', stated_value=6) を使って認識された候補をすべて列挙し、パーツの実際の軸と、リクエストフレームを適切に回転させたすべての状態を確認します（それぞれの状態が選択する候補ごとにグループ化されます）。interface_features() は、穴を持つ平面を提案します。保護する穴のハンドルを選択してください。単純な貫通穴の場合、edit_feature(handle, diameter=8, protected_refs='["@feature[...]"]') でサイズを変更し、増減した体積の予測値と測定値を報告します。穴、その他の認識された穴、外形がチェックに合格した場合にのみ、結果が登録されます。座ぐり、スポットフェース、皿穴、または複数の構成面を持つ穴は編集できません。こうした穴は execute() で編集し、compare(kind="shape") と STEP エクスポートのゲートで検証してください。

通常は、MCP ツールを明示的に使い、エクスポート前に結果を検証するようアシスタントに依頼すると効果的です。たとえば、次のようにします。

Use build123d-mcp. Build this incrementally, render after the main features,
measure the final dimensions, run validate(), and export STEP if it passes.

GitHub Codespaces と Copilot で試す

GitHub Codespaces を使って、ブラウザーでプロジェクトを実行することもできます。

GitHub Codespaces で開く

初心者にとって、これは「GitHub ホストの LLM ＋ MCP」を試す最も手軽な方法です。

• GitHub Codespaces では、ブラウザー上で VS Code を利用できます。
• GitHub Copilot Chat が LLM アシスタントを提供します。
• build123d-mcp は、MCP CAD ツールサーバーとして codespace 内で動作します。

LLM を利用するには、GitHub Copilot へのアクセス権が必要です。codespace 自体には、プロジェクトがすでにチェックアウトされ、適切な Python/CAD 依存関係がインストールされた使い捨てのワークスペースが用意されています。次のような場合に便利です。

• ノート PC の環境を変更せずにプロジェクトを試す
• コントリビューションを行う前にテストを実行する
• 同じブラウザーのワークスペースで Copilot Chat と build123d-mcp を一緒に使う

GitHub のドキュメントでは、次の内容を説明しています。

• Codespaces で Copilot を使用する
• MCP で Copilot Chat を拡張する

このリポジトリには、Python 3.12、uv、およびヘッドレスレンダリングに必要な Linux ディスプレイパッケージをインストールする開発コンテナーが含まれています。また、GitHub Copilot の VS Code 拡張機能をインストールし、ワークスペース用の MCP 設定ファイル .vscode/mcp.json も含まれています。

codespace を開くと、次のコマンドが実行されます。

uv sync --all-groups

開発環境のインストールを確認するには、次のコマンドを実行します。

uv run build123d-mcp --version
uv run pytest

Copilot をローカルの CAD サーバーと一緒に使うには、次の手順に従います。

1. codespace を開きます。
2. セットアップが完了するまで待ちます。
3. Copilot Chat を開き、Agent モードを選択します。
4. .vscode/mcp.json を開き、VS Code がまだ起動していない場合は build123d-mcp サーバーを起動します。
5. 前のセクションにある最初のテスト用プロンプトを入力します。

Codespaces の MCP 設定は、PyPI パッケージではなく、ローカルのチェックアウトを参照します。

{
  "servers": {
    "build123d-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "build123d-mcp"]
    }
  }
}

Codespaces は、プロジェクトを試したり、コントリビューションしたり、GitHub Copilot と build123d-mcp を同じリモート環境で使ったりするのに適しています。自分のマシンでデスクトップ AI アプリを使う場合は、通常の uv tool run ... build123d-mcp@latest セットアップのほうが簡単です。これらのアプリは、MCP サーバーをローカルで起動することを想定しているためです。

できること

build123d-mcp は、アシスタントに次のツールを提供します。

• 永続的な CAD セッションで build123d コードを実行する
• PNG、SVG、DXF のプレビューをレンダリングする
• 体積、面積、バウンディングボックス、トポロジー、重心を測定する
• 穴、ボス、皿穴、穴パターンを検出する
• 印刷可能性、嵌合／位置合わせの比較、エクスポートの有効性を確認する
• 比較用に STEP/STL ファイルをインポートする
• STEP、STL、DXF、SVG、または複数の形式を一度にエクスポートする
• セッションのスナップショットを保存および復元する
• 2D の技術図面プレビューを生成する

ツールとリソースの全リファレンスについては、llms.md を参照してください。

アシスタント向けガイダンス

このサーバーには、アシスタントが CAD のワークフローを適切に進めるためのガイダンスが含まれています。これは、プロジェクトのガイダンスファイルを読み込むコーディングエージェントで特に役立ちます。

サーバーへの接続後、必要なワークフローに応じて install_skill を呼び出すようアシスタントに依頼してください。

install_skill(target="agents-md", skill="modeling")
install_skill(target="agents-md", skill="drawing")
install_skill(target="agents-md", skill="repair")

install_skill は target="claude"、"cursor"、"windsurf" にも対応しています。3D パーツには skill="modeling"、技術図面には skill="drawing"、ソリッドの検証に失敗した場合は skill="repair" を使用します。

default_prompt.md を AI アプリにシステムプロンプトとして貼り付けることもできます。

開発環境のセットアップ

ローカルで開発するには、次のコマンドを実行します。

git clone https://github.com/pzfreo/build123d-mcp.git
cd build123d-mcp
uv sync --all-groups
uv run build123d-mcp --version
uv run pytest

このチェックアウトから AI アプリでサーバーを実行するには、次のコマンドを使用します。

command: uv
args:    ["run", "build123d-mcp"]

コントリビューションのガイドラインについては、CONTRIBUTING.md を参照してください。

高度な使い方

デフォルトの stdio トランスポートでは、各アプリのプロセスに専用の分離されたセッションが割り当てられます。 HTTP モードは、Web、コンテナー、またはリモートでのデプロイに利用できます。

uv tool run --python 3.12 "build123d-mcp[http]@latest" \
  --transport http --host 127.0.0.1 --port 8000

HTTP 対応アプリは、次の接続先に接続します。

http://localhost:8000/mcp

HTTP モードには認証機能が組み込まれておらず、ホストがリクエストごとのセッションミドルウェアを提供しない限り、共有の CAD セッションが 1 つ使用されます。複数のユーザーに直接公開しないでください。

その他の高度なトピック：

• セキュリティモデルとサンドボックス化：security.md
• ツールの完全なリファレンス：llms.md
• ライブセッションビューアー：docs/live-viewer.md
• 変更履歴：CHANGELOG.md

ステータス

開発中。