FreeCAD MCP

freecad-mcp

これは何をするものですか

これは、AI エージェントとFreeCADをつなぐブリッジです。パラメトリック設計、CNC ツールパス生成、メッシュ作業のための思考パートナーとして機能します。設計の意図と専門分野の判断はあなたが担い、エージェントが FreeCAD の操作を処理します。協力することで、より速く作業を進め、手作業では何時間もかかるものを一緒に設計し、FreeCAD がよく生成する難解なエラーメッセージを解きほぐし、ひとりでは見つけるのがほぼ不可能な、見つけにくく厄介なモデリングの問題を探し出せます。これはデモではなく、部品の設計、ツールパスの生成、印刷や切削といった日常的な個人利用を想定して作られています。ツールの全リファレンスについては、TOOLS.mdをご覧ください。

一緒に取り組めること

• 設計を練り上げる — 「取り付けプレートが必要です。100x60mmでM3の穴が4つ、角は丸くします。どう進めるのがよいでしょうか？」要件と制約はあなたが提示し、エージェントが作成を進め、詳細が不足している判断事項を指摘しながら、一緒に反復して設計を練り上げます。
• 問題の原因を診断する — 「このスケッチをパッドしようとしたら、変な結果になりました。FreeCADは実際には何を伝えているのでしょうか？」エージェントはレポートビューを読み取り、スケッチの拘束を調べ、対処できる形で状況を説明します。
• 既存の部品を改良する — 「この壁は薄すぎる気がしますし、フィレットは印刷に耐えられないかもしれません。一緒に確認しましょう」
• CNC ツールパスを計画する — 「このポケットを切削したいです。材料に合った工具とパラメーターを一緒に検討しましょう」
• 再利用できるものを作る — 「ブラケットを作るたびに同じワークフローを繰り返しています。寸法のスプレッドシートからブラケットを生成するマクロを書きましょう」
• 確定する前に作業内容を確認する — 「このモデルにジオメトリエラーはありますか？」「この壁は印刷に耐えられますか？」「これらの部品がぶつかることはありませんか？」
• メッシュを扱う — 「メーカーからSTLを受け取りました。FreeCADに取り込んで、取り付け用の形状を追加しましょう」
• 製造用にエクスポートする — 「これをSTEPとしてエクスポートし、CNCルーター用のGコードを生成してください」

使用例

MCPを使った例をいくつか紹介します。

壊れた外部参照のデバッグ — FreeCADが復元できないリンク、モデルについて把握していることと矛盾しているように見えるエラーメッセージ、そしてファイルを直接読んで見つけた1行の修正。

全体を見る →

---

屋根材ジェネレーターの設計 — スプレッドシートのパラメーターをもとに、あらゆる屋根面を覆うパラメトリックジェネレーターを設計するために、数回にわたってやり取りしました。

全体を見る →

---

はじめに

FreeCAD のバージョンサポート： CAM を除くすべてのツールは、FreeCAD 1.1.x（現行の安定版）でサポートされています。CAM のツールパス生成には、現行の FreeCAD ウィークリーデベロップメントビルドが必要です（上流でカレンダーベースのバージョン管理に移行する前は「1.2-dev」と呼ばれていたもので、例：26.3.x）。Path ワークベンチの API は 1.1 と開発版系列の間で互換性のない変更が加えられています。このプロジェクトは最新のウィークリービルドを追跡しています。

Claude Code を使い、macOS で開発されています。コードは macOS、Windows、Linux に対応しています。ほかのプラットフォームでも動作するはずですが、テストは十分ではありません。他のエージェントやプラットフォーム向けの PR も検討します。また、Claude 以外でもプロトコルの往復が正常に行われることを確認するため、LM Studio のネイティブ MCP クライアント（qwen/qwen2.5-coder-14b、qwen/qwen3-32b、google/gemma-4-e4b）でも手動のスモークテストを実施しています。詳細と注意事項については、AGENT-INSTALL.md を参照してください。

AI エージェントに次のように伝えてください。

https://github.com/blwfish/freecad-mcp にアクセスし、AGENT-INSTALL.md ファイルを読んでください。手順に従って、このマシンに FreeCAD MCP サーバーをインストールして設定してください。

残りの作業はエージェントが行います。前提条件のインストール、リポジトリのクローン、FreeCAD アドオンのセットアップ、エージェント自身の登録などを実施します。セットアップが完了したら、エージェントに部品の設計を依頼できます。

インストールの確認

AICopilot ワークベンチを読み込んだ状態で FreeCAD を起動し、「レポートビュー」を開きます（メニュー：表示 → パネル → レポートビュー）。次のような表示が出ます。

この出力について、知っておくとよい点をいくつか紹介します。

• AI Copilot Service starting — AICopilot ワークベンチが正しく読み込まれたことを示します。この表示がない場合、アドオンがインストールされていないか、FreeCAD がアドオンを見つけられていません。
• デバッグ／クラッシュ関連の基盤を読み込み済み — 計測機能が有効になっています。操作中に問題が発生した場合、ログとクラッシュレポートが自動的に記録されます。
• ソケットサーバー起動済み／Claude ready — ブリッジが接続を待ち受けています。この行は、AI エージェントが接続できることを示します。
• フォントエイリアスの警告（オレンジ色）— 何をしていても、ほとんどの macOS システムで表示される無害な Qt のメッセージです。問題ありません。

FreeCAD の複数インスタンスを実行する

MCP は複数の FreeCAD インスタンスと同時に通信できます。たとえば、ローカルのデバッグビルドと標準リリースを比較したり、メインの作業を開いたまま別ウィンドウでリグレッションテストを実行したり、同じ Claude セッションからヘッドレスワーカーを操作したりする場合に便利です。

各 FreeCAD プロセス（GUI またはヘッドレス）は、起動時に UUID を生成し、独自のソケットを /tmp/freecad_mcp_<uuid>.sock でバインドして、~/.cache/freecad-mcp/instances/<uuid>.json に検出ファイルを書き込みます。ブリッジは、このディレクトリをスキャンして、起動したユーザーにかかわらず実行中のインスタンスを検出します。

起動時に指定できる環境変数：

• FREECAD_MCP_LABEL=<name> — インスタンスに人間が読みやすい名前を付けます（指定しない場合は UUID が使われます）
• FREECAD_MCP_SOCKET=<path> — ソケットのパスを完全に上書きします（CI や厳密にスクリプト化された起動で使うための回避策です）

エージェントから一覧表示して切り替える：

list_freecad_instances          # all live instances + active doc info
select_freecad_instance uuid=<id>           # by uuid
select_freecad_instance label="weekly"      # or by label

エージェントから起動する：

spawn_freecad_instance gui=true label="private" \
    freecad_binary=/path/to/your/private/build/bin/FreeCAD
spawn_freecad_instance gui=true label="weekly" \
    freecad_binary=/Applications/FreeCAD.app/Contents/MacOS/FreeCAD

インスタンスが明示的に選択されていない場合の解決ルール：実行中が 0 個 → エラー、1 個 → 自動選択、2 個以上 → 一覧を表示してエラー（select_freecad_instance を呼び出してください）。

開発者向け

# Unit tests (1430 tests, no FreeCAD required)
python3 -m pytest tests/unit/

# Integration tests (147 tests, requires running FreeCAD with AICopilot loaded)
python3 -m pytest tests/integration/

# All tests with coverage
python3 -m pytest --cov=AICopilot

プロンプトキャッシュとClaude APIの直接呼び出し

Claudeユーザーにとって、最も簡単で費用も抑えられる方法は、Claude Code、ウェブインターフェース、またはCLIツールを直接使うことです。 これらのプラットフォームは、プロンプトキャッシュとコスト最適化を自動的に処理するため、意識する必要はありません。このMCPをFreeCADでパーツを設計するためだけに使うのであれば、Claude Codeをお使いください。このセクションを読む必要はありません。

Anthropic SDKを使ってClaude APIを直接呼び出すアプリケーションや統合機能を構築する場合は、プロンプトキャッシュを理解しておく必要があります。Claudeデスクトップアプリ、ウェブインターフェース、CLIツールは、ファイルコンテキストとツール参照のキャッシュを自動的に処理します。この最適化は表示されませんが、同じコンテキストに対するクエリを繰り返す際のレイテンシとコストを削減します。

APIを直接呼び出す場合、キャッシュは明示的に管理する必要があります。MCPサーバー自体はAPIを呼び出しませんが、呼び出しを行う統合機能や拡張機能を構築する場合は、次の点にご注意ください。

• デプロイ前に、プロンプトキャッシュに関するAnthropic SDKのドキュメントを読む
• キャッシュTTL（通常5分）とコストへの影響（入力トークンの20%）を理解する
• キャッシュキーにはモデル、システムプロンプト、正確なトークン境界が含まれることに注意する。わずかな違いでもキャッシュが無効になります
• コンテキストが頻繁に更新される場合（ドキュメント状態のスナップショットなど）は、キャッシュが無効になるリスクを考慮する

同様に、他のMCPサーバーやエージェントをワークフローに統合する場合、READMEに記載されていない同様の注意点がある可能性があります。キャッシュの動作、非同期ジョブの処理、トークン制限についてドキュメントやソースを確認し、Claude Codeと同じように動作すると決めつけないでください。

テストスイートでは、ユニットテストによってハンドラーディスパッチ層、基盤インフラストラクチャ、ドキュメント操作をテストします。また、ライブのFreeCADインスタンスに対する統合テストによって、Part、PartDesign、Sketch、Draft、Boolean、Transform、Measurement、CAMの各ワークフローをエンドツーエンドでテストします。CIでは、プッシュごとに両方のテストスイートを実行します。

組み込みの診断機能

MCPには、操作ログ、クラッシュの記録、レポートビューへのアクセス機能が含まれています。FreeCAD独自のエラー報告は理解しにくいことがよくあります。OCCTカーネルのクラッシュは痕跡を残さず、表示されるメッセージも解釈するにはコンテキストが必要です。これらのツールは、そのコンテキストを提供します。

このインフラストラクチャの存在は、必要になるまでほとんどのユーザーや開発者には知られていません。実際の例を含む詳細なガイドはdocs/diagnostics.md、問題が発生した際にエージェントが従うべき調査手順はAGENT-DEBUGGING.mdをご覧ください。

技術的な詳細、アーキテクチャ、貢献ガイドライン、新しいツールの追加方法については、AGENT-INSTALL.mdをご覧ください。

セキュリティ

このツールは設計上、AIエージェントにFreeCADのPython環境への完全なアクセス権を付与します。これにはファイルシステムとOSも含まれます。また、エージェントはドキュメントの内容（オブジェクトのラベル、マクロのソース、スプレッドシートの値）を推論コンテキストに直接読み込むことも意味するため、信頼できないソースから入手したFreeCADファイルは、信頼できないコードと同じように扱ってください。セキュリティモデルの詳細、実用的な緩和策、脆弱性の報告方法については、SECURITY.mdをご覧ください。

MCPは1日に1回、GitHubを確認して新しいリリースがないか調べます。これはGitHubの公開APIへの単純なプルで、結果はキャッシュされ、監査できるようにローカルの~/.cache/freecad-mcp/version_check.logに記録されます。詳細はSECURITY.mdをご覧ください。

問題の報告

バグを見つけた場合は、issueを作成してください。何も通知されないまま失敗しても、誰の役にも立ちません。問題があってもエージェントは知らせず、ただタスクに失敗します。有用な報告に必要な内容については、CONTRIBUTING.mdをご覧ください。

ライセンス

LGPL-2.1-or-later