🛠️ Claude Desktop 與 FreeCAD MCP 整合安裝與操作教學

本指南將引導您如何透過 MCP (Model Context Protocol) 將 Claude Desktop 與 FreeCAD 進行連結，實現透過自然語言直接控制 FreeCAD 進行 3D 建模。

📋 事前準備

1. FreeCAD 1.0+（建議使用 FreeCAD 1.1 或更新版本，下載網址: https://www.freecad.org/downloads.php?lang=zh_TW）。

2. Claude Desktop 應用程式（需登入帳號）。

3. FreeCADMCP 插件專案檔（包含 InitGui.py 及 MCP 核心代碼，下載或 Clone neka-nat/freecad-mcp 專案）

📂 第一階段：安裝 FreeCAD MCP 插件

1. 定位 FreeCAD Mod 目錄：

   在 Windows 系統中，開啟檔案總管並前往以下路徑（請將 v1-1 替換為您的 FreeCAD 版本號，或直接貼上路徑）：

   Plaintext

   C:\Users\<您的使用者名稱>\AppData\Roaming\FreeCAD\v1-1\Mod\
   

   快捷技巧：可按下 Win + R，輸入 %APPDATA%\FreeCAD\ 後按下 Enter，再進入對應版本的 Mod 資料夾。

2. 放置插件資料夾：

   • 將下載好的 FreeCADMCP（或 freecad-mcp）資料夾複製到 Mod 資料夾內。

   • 關鍵檢查：確保 InitGui.py 位於 Mod/FreeCADMCP/InitGui.py 的第一層層級，切勿多包一層同名資料夾。

     
     
     

3. 啟動 FreeCAD RPC 服務：

   • 開啟 FreeCAD 應用程式。

   • 在上方工作區（Workbench）下拉選單中選擇 MCP（或 FreeCADMCP）。

     
     
     

   • 點擊工具欄上的 Start RPC Server。

   
   
   

   • 檢視底部狀態列或主頁面，確認顯示 RPC Server running on 127.0.0.1:8000 訊息。

⚙️ 第二階段：設定 Claude Desktop

1. 開啟 Claude 設定檔：

   • 開啟 Claude Desktop。

   • 點擊左上角選單的 Settings $\rightarrow$ 切換至 Developer 頁籤 $\rightarrow$ 點擊 Edit Config。

     
     
     

   • 或直接在檔案總管網址列輸入並開啟：

     Plaintext

     %APPDATA%\Claude\claude_desktop_config.json
     

2. 編輯 JSON 設定：

   在 mcpServers 區塊中加入 freecad 的配置（若已有其他服務，請記得用逗號 , 分隔）：

   JSON

   {
     "mcpServers": {
       "freecad": {
         "command": "uvx",
         "args": [
           "freecad-mcp",
           "--only-text-feedback"
         ]
       }
     }
   }
   

   💡 提示：加入 --only-text-feedback 參數可減少圖像或冗餘資料傳輸，有效降低 Token 消耗並提升指令回應速度。

   

   
   

3. 重啟 Claude Desktop：

   • 徹底關閉 Claude Desktop（請至右下角 Windows 系統工作列，對 Claude 圖示點右鍵選擇 Exit）。

   • 重新開啟 Claude Desktop。

🔍 第三階段：驗證連線狀態

1. 開啟 Claude Desktop，點擊左側設定 $\rightarrow$ Connectors（或 Settings $\rightarrow$ Extensions）。

2. 在列表中尋找 freecad。

   
   
   





3. 若狀態顯示 Desktop | Local dev 且帶有綠色打勾符號 ✓，代表 MCP 服務已成功連線！

🚀 第四階段：實測與對話建模

1. 建模前確認

• 確保 FreeCAD 保持開啟狀態。

• 確保 FreeCAD 內的 Start RPC Server 處於執行狀態。

2. 自然語言指令範例

您可以直接在 Claude Desktop 的對話框中輸入中文指令，Claude 會自動轉化為 Python 腳本並發送至 FreeCAD 執行：

• 基礎幾何建模：

  "請幫我在 FreeCAD 建立一個新文件，並繪製一個長 80mm、寬 40mm、高 15mm 的方塊，且在四個垂直角落做 5mm 的倒角 (Fillet)。"

• 特徵修改與加工：

  "請在這個長方體正中心挖一個直徑 25mm 的貫穿圓孔。"

• 檔案管理與匯出：

  "請幫我把當前模型匯出成 STEP 格式檔案，儲存於桌面。"

❓ 常見問題與排障 (Troubleshooting)

現象 / 問題	可能原因	解決方法
Claude 找不到 freecad 工具	claude_desktop_config.json 格式錯誤或未徹底重啟 Claude	檢查 JSON 語法（逗號、括號是否對齊），並至工作列完全 Exit Claude 後重開啟。
指令發送後 FreeCAD 無反應	FreeCAD 的 RPC Server 未啟動	切換至 FreeCAD 的 MCP 工作區，重新點擊 Start RPC Server。
插件未出現在 FreeCAD 工作區	資料夾層級擺放錯誤	確認 InitGui.py 的路徑為 .../Mod/FreeCADMCP/InitGui.py，而非 .../Mod/FreeCADMCP/FreeCADMCP/InitGui.py。