FreeCAD Addin ＆ MCP Server for AIエージェント

バージョン: 0.9.0

このプロジェクトは、Claude DesktopまたはCodex DesktopなどのAIエージェントがFreeCADを直接操作するためのModel Context Protocol (MCP)サーバーです。このツールをAIエージェントに追加することで、チャットのプロンプトを通じて3Dモデルの作成、編集、情報取得が可能になります。

このサーバーは、FreeCAD内で動作するPythonマクロ（freecad_mcp_addon.py）と連携して機能します。

• 作者: Kanbara Tomonori

• X (旧Twitter): @tomo1230

• ライセンス: MIT License

概要とアーキテクチャ

このツールは、AIエージェントとの対話を通じて、直感的かつ自然言語ベースでFreeCADのモデリング作業を行うためのブリッジとして機能します。

このREADMEでは、Claude Desktop / Codex / Claude Code の3パターンに分けてセットアップ方法を説明します。

処理フロー:

1. ユーザーがAIエージェントのチャットで自然言語でプロンプトを送信します。（例: 50mmの立方体を作って）MCPツールはClaudeが自動的に認識・使用するため、特別なプレフィックスは不要です。

2. AIエージェントは、このNode.jsサーバー（freecad_mcp_server.js）を子プロセスとして起動し、CallToolRequest を送信します。

3. Node.jsサーバーはリクエストをJSONコマンドに変換し、http://127.0.0.1:8765/command に HTTP POST します。

4. FreeCAD内で実行中のPythonマクロ（freecad_mcp_addon.py）がHTTPサーバーとして待ち受けており、リクエストを受信してFreeCADのPart APIを実行します。

5. Pythonマクロは実行結果をHTTPレスポンスとして返します。

6. Node.jsサーバーがレスポンスを受け取り、AIエージェントに結果を返します。

7. AIエージェントがその結果を解釈し、ユーザーに応答します。

ポート設定: デフォルトは 127.0.0.1:8765。環境変数 FREECAD_MCP_HOST / FREECAD_MCP_PORT で変更可能です。

Related MCP server: FreeCAD MCP Server

セットアップ

まずは全エージェント共通の準備を行い、その後に使いたいクライアントごとの設定を追加します。

どのクライアントを使うか

Step 1: 共通の前提条件

• Node.js: v18以降がインストールされていること。(https://nodejs.org/ja/download)

• FreeCAD: バージョン 1.0以降がインストールされていること。(https://www.freecad.org/)

• このリポジトリ: freecad_mcp_server.js と freecad_mcp_addon.py を使える状態にしておくこと

Step 2: 共通のインストール

1. 任意の場所にこのリポジトリをクローンします。

   git clone https://github.com/tomo1230/freecad_mcp_server

2. ターミナルでディレクトリに移動し、依存関係をインストールします。

   cd freecad_mcp_server
   npm install @modelcontextprotocol/sdk

Step 3: FreeCADでマクロを起動

1. FreeCADを起動します。

2. メニューから マクロ → マクロを実行... を選択します。

3. このリポジトリの freecad_mcp_addon.py を選択して実行します。

4. FreeCADのコンソールに [MCP] FreeCAD MCP Addon started. API endpoint: http://127.0.0.1:8765/command と表示されれば待ち受け状態です。

注意: FreeCADを再起動するたびにマクロの再実行が必要です。

Step 4: 回帰テストの実行（任意）

FreeCAD MCP の全ツールをまとめて確認したい場合は、freecad_mcp_addon.py マクロを実行した状態で次を実行します。

npm run test:regression

PowerShell で npm 実行がブロックされる環境では、次を使ってください。

npm.cmd run test:regression

この回帰テストでは以下を確認します。

• 57 個の MCP ツールをすべて実行できること

• 形状作成、ブール演算、計測、スケッチ拘束、保存、エクスポートが成功すること

• get_edges_info が複合形状でも失敗しないこと

• extrude_sketch が閉じたスケッチで正常動作すること

実行後は作業ディレクトリに次の成果物が生成されます。

• regression_all_tools_<timestamp>.fcstd

• regression_comboAll_<timestamp>.stl

Claude Desktop のセットアップ

GUI の Claude Desktop から FreeCAD を操作したい場合の手順です。

前提

• Claude Desktop: アプリケーションがインストールされていること。（https://claude.ai/download）

設定手順

1. Claude Desktopを開き、左上のツールメニューからファイル＞設定の画面に移動します。

2. 「設定を編集」のボタンをクリックします。

3. claude_desktop_config.json に以下を追加します。リポジトリにはサンプルとして .claude/claude_desktop_config.json も含まれています。

   {
     "mcpServers": {
       "freecad": {
         "command": "node",
         "args": ["/path/to/freecad_mcp_server/freecad_mcp_server.js"],
         "env": {
           "FREECAD_MCP_HOST": "127.0.0.1",
           "FREECAD_MCP_PORT": "8765"
         }
       }
     }
   }

注意: env の設定はデフォルト値なので省略可能です。FreeCADのHTTPサーバーポートを変更した場合のみ指定してください。

使用例

• 幅50、奥行き30、高さ20の箱を作って

• "MyCube" という名前の立方体を作成して、その寸法を教えて

• 最後に作ったボディに半径2mmのフィレットを追加して

Codex のセットアップ

Codex からこの MCP サーバーを呼び出したい場合の手順です。

前提

• Codex: アプリまたはCLIがインストールされていること

設定手順

1. Codex の設定ファイルに freecad サーバーを追加します。

2. リポジトリにはサンプルとして .codex/config.toml が含まれています。

3. パスを自分の環境に合わせて freecad_mcp_server.js へ向けてください。

approval_policy = "never"

[mcp_servers.freecad]
command = "node"
args = ["C:\\freecad_mcp_server\\freecad_mcp_server.js"]
enabled = true
alwaysAllow = true

補足

• alwaysAllow = true にすると、Codex から FreeCAD MCP ツールを毎回確認なしで使えます。

• FreeCAD 側では、事前に freecad_mcp_addon.py を起動しておく必要があります。

• ホストやポートを変える場合は、Codex 側の設定ではなく環境変数 FREECAD_MCP_HOST / FREECAD_MCP_PORT を使って Node.js サーバー側を調整してください。

使用例

• 50mmの立方体を作って

• 円柱を作ってから上面に半径3mmのフィレットを追加して

• いまあるボディ一覧を教えて

Claude Code のセットアップ

Claude Code では、MCPサーバー設定そのものよりも、SKILL.md を導入してモデリング時のツール実行順序を安定させる使い方を想定しています。

Claude Desktop のチャット設定とは別です。こちらは Claude Code（ターミナル版） 向けの説明です。

SKILL.md の役割

インストール方法

1. スキルディレクトリを作成します。

   %APPDATA%\Claude\local-agent-mode-sessions\skills-plugin\<session-id>\<sub-id>\skills\freecad-modeling-order\

2. 上記ディレクトリに SKILL.md をコピーします。

3. 同ディレクトリの manifest.json の "skills" 配列に以下を追加します。

   {
     "skillId": "freecad-modeling-order",
     "name": "freecad-modeling-order",
     "description": "FreeCAD MCPツールを使って3Dモデリングを行う際に、ツールの正しい実行順序を参照・適用するためのスキル。...",
     "creatorType": "user",
     "updatedAt": "2026-03-27T00:00:00.000Z",
     "enabled": true
   }

4. Claude Code を再起動すると自動的にスキルが有効になります。

このスキルが有効な場面

• コーヒーカップ・ボトル・容器など複合形状の作成

• ブール演算（結合・切除）とシェル化の組み合わせ

• フィレット・面取り・パターン・ミラーを含む複数ステップ作業

• スウィープ・ロフト形状の作成

モデリングベストプラクティス / ツール実行順序

複雑な形状を確実に作るためには、ツールの実行順序が重要です。 順序を間違えるとブール演算が失敗したり、フィレットが適用できなくなる場合があります。

🔑 基本原則（全モデルに共通）

形状作成・配置 → ブール演算（結合/切除） → シェル化 → パターン/ミラー → フィレット/面取り → 保存/エクスポート

📋 ケース別ベストプラクティス

① コーヒーカップ（取っ手付きの容器）

NG順序: カップをシェル化 → 取っ手を結合 → シェル済みの薄肉ボディへのブール演算は失敗しやすい

✅ 正しい順序:
1. create_cylinder          ── カップ本体（ソリッド）
2. create_pipe / create_cylinder  ── 取っ手（ソリッド）
3. move_by_name / rotate_by_name  ── 取っ手を正しい位置に配置
4. combine_by_name (join)   ── 本体 + 取っ手 を一体化（ソリッド同士）
5. shell_body               ── 一体化後に中空化（厚み・開口面を指定）
6. add_fillet               ── 最後に角を丸める
7. export_file              ── 完成後にエクスポート

② ボルト穴パターン（円形配列で複数穴）

NG順序: 穴を1つ切除 → パターン複製 → 切除後の複雑形状をパターン化するとインデックスがずれる

✅ 正しい順序:
1. create_cylinder                    ── 本体
2. create_cylinder                    ── 穴ツール（1個）
3. move_by_name                       ── 穴ツールを1か所目の位置へ
4. create_circular_pattern            ── 穴ツールを円形配列（切除前にパターン化）
                                         axis="z", quantity=4, angle=360
5. combine_selection (cut)            ── 本体からパターン全穴を一括切除
6. add_chamfer                        ── 穴の入り口を面取り（最後）
7. export_file

③ 左右対称部品（ミラーコピー）

NG順序: フィレット追加 → ミラーコピー → 結合 → フィレット後の複雑形状を結合すると接合部に問題が起きやすい

✅ 正しい順序:
1. create_sketch + draw_*   ── 片側の断面スケッチ
2. add_*_constraint / add_*_dimension  ── 拘束・寸法を確定
3. extrude_sketch            ── 押し出してソリッド化
4. copy_body_symmetric       ── ミラーコピー（フィレット前）
5. combine_by_name (join)    ── 両側を結合（ソリッド同士）
6. add_fillet                ── 結合後に丸め処理（最後）
7. export_file

④ スイープ/ロフト形状（パイプ継手・ブレンド形状）

NG順序: sweep_sketch を呼ぶ → その後でパスを作成 → スケッチが存在しないと実行エラーになる

✅ 正しい順序:
1. create_sketch (plane=yz) ── 断面プロファイルのスケッチを先に用意
2. draw_circle_in_sketch    ── 断面形状を描く
3. create_sketch (plane=xy) ── パス用スケッチを用意
4. draw_line_in_sketch      ── パス形状を描く
5. sweep_sketch             ── プロファイル + パス の両方が揃ってから実行
6. add_fillet               ── 最後

loft_sketches も同様に、全プロファイルスケッチを先に作成してから呼び出す。

⑤ 干渉チェック → ブール演算

位置ずれのまま切除すると意図しない形状になる

✅ 正しい順序:
1. create_* / move_by_name  ── ツールボディを配置
2. check_interference       ── 干渉を確認（Trueなら重なっている）
3. combine_by_name (cut)    ── 干渉を確認してから切除

⚙️ ツールごとの推奨呼び出し順序まとめ

【形状作成フェーズ】
  create_box / create_cylinder / create_sphere ...
  create_sketch → draw_* → add_*_constraint → add_*_dimension
  extrude_sketch / revolve_sketch / loft_sketches / sweep_sketch

【配置フェーズ】
  move_by_name / rotate_by_name
  ↓ (任意) check_interference で干渉確認

【ブール演算フェーズ】
  combine_by_name / combine_selection / combine_selection_all

【中空化フェーズ】  ← ブール演算（結合）の後
  shell_body

【パターン/ミラーフェーズ】
  create_circular_pattern / create_rectangular_pattern
  copy_body_symmetric

【仕上げフェーズ】  ← 必ず最後
  add_fillet / add_chamfer

【情報確認フェーズ】  ← 任意のタイミングで
  get_all_bodies / get_body_dimensions / get_bounding_box / get_body_center
  get_edges_info / get_faces_info  ← フィレット前にインデックス確認
  get_mass_properties / get_body_relationships
  measure_distance / measure_angle / check_interference

【出力フェーズ】  ← 最後
  save_document / export_file

⚠️ 注意が必要なツール

APIリファレンス / 利用可能なツール

Claudeは以下のツールを呼び出すことでFreeCADを操作します。

形状作成ツール (10種)

配置パラメータ補足: cx/cy/cz は中心座標。x_placement（left/center/right）・y_placement（front/center/back）・z_placement（bottom/center/top）で基準点を変更できます（対応ツールのみ）。

スケッチ作成・描画ツール (4種)

スケッチ拘束・寸法ツール (8種)

スケッチからソリッド生成ツール (4種)

編集・修正ツール (6種)

ブール演算ツール (3種)

変換・表示ツール (5種)

情報取得・測定ツール (11種)

ユーティリティ (6種)

🟢 できること

• 基本形状作成 - 直方体、立方体、円柱、球、円錐、トーラス、半球、半トーラス、多角柱、パイプ（10種）

• スケッチモデリング - 2D図形描画（矩形・円・直線）＋ 押し出し・回転・スイープ・ロフトでソリッド化

• スケッチ拘束 - 水平・垂直・平行・垂直（直角）・一致・接線拘束、線形・半径寸法

• 編集操作 - フィレット、面取り、シェル化（中空化）、断面ビュー作成

• パターン作成 - 円形・矩形配列、ミラーコピー

• ブール演算 - 結合、切除、交差（2ボディ指定・複数選択・全体一括）

• 変換 - 移動、回転、表示/非表示

• 情報取得 - 寸法、体積、質量特性、エッジ/面情報、2ボディ間距離・角度・干渉チェック

• ファイル操作 - FreeCAD形式で保存、STEP/STL/OBJ/FCStdでエクスポート

• Undo/Redo - 操作単位での元に戻す・やり直し（トランザクション対応）

🔴 できないこと

• 自由曲面 - NURBS曲面、有機的な形状

• アセンブリ - 複数部品の組み立て・拘束

• 解析・製造 - CAM、FEA（有限要素解析）、レンダリング

• 図面作成 - 2D図面（TechDrawワークベンチ）の自動生成

• 複雑なスケッチ - 多くの要素・拘束・関係性を持つ2Dスケッチ

使用例

YouTube モデるんですAI チャンネル

「しゃべるだけで、世界がカタチになる。」 ことばが、モノになる時代。 『ModerundesuAI』は、AIと会話するだけで3Dモデリングができる、 未来のモノづくり体験をシェアするYouTubeチャンネルです。 Fusion 360やBlenderなどのCADソフトとAI（ChatGPTやClaude）を連携させて、 プロンプト（命令文）でリアルな“カタチ”を自動生成。 初心者からモデリング好きまで、誰でも「つくる楽しさ」に触れられるコンテンツを発信します！

https://www.youtube.com/@ModerundesuAI

「FreeCADでサイコロを設計して」Claude AI＆FreeCAD API 連携🤖AIモデリングチャレンジ！💪 「FreeCADで400mlの水が入るコップを設計して」Claude AI＆Autodesk Fusion API 連携🤖AIモデリングチャレンジ！💪 「FreeCADで手すり付きの螺旋階段を設計して」Claude AI MCP ＆ FreeCAD API 連携🤖AIモデリングチャレンジ！💪

関連記事（note）

AIエージェントに「FreeCADでこれ作って」と話しかけるだけで、3Dモデリングできる時代が来た！？

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。