FreeCAD + MCP AI 제어 환경 구축 가이드

2026-10-14 업데이트: 이 환경에서 실무 DWG를 다루며 발견한 패치 4종(치수 서식 코드·자동 피팅·다국어 인코딩·디버그 print)을 FreeCAD + MCP 가이드 업데이트로 정리했습니다.

AutoCAD 없이 무료 FreeCAD 1.1.3을 AI 에이전트로 자동 조종하는 환경 구축 가이드다. ODA 변환기 연동, MCP 설치 4단계, DWG 워크플로우, CNC·3D 프린팅 확장, 실전 검증 10항목 결과와 트러블슈팅까지 정리했다.

대상: AutoCAD 없이 무료 CAD로 3D 설계를 하고, AI(ZCode 등 MCP 클라이언트)에게 명령해 FreeCAD를 자동 조종하고 싶은 사용자
검증 환경: Windows 11 (build 26200) / FreeCAD 1.1.3 / 설치·테스트 완료일 2026-09-07 (2차 갱신: 탐색기 연결·텍스트 설정·샘플 데모 포함)
이 워크스페이스에는 전부 설치·테스트가 끝나 있습니다. 이 문서는 재구축·확장·문제해결용 기록입니다.

1. 소개 — 이 조합이 무엇인가

1.1 왜 FreeCAD인가

1.2 구성요소

1. FreeCAD 1.1.3        — 3D CAD 본체 (무료)
2. ODA File Converter   — DWG↔DXF 변환기 (Open Design Alliance 제공 무료 유틸리티)
3. FreeCADMCP 애드온    — FreeCAD 안에서 RPC 서버(포트 9875)를 띄우는 플러그인
4. freecad-mcp (PyPI)   — MCP 클라이언트(ZCode 등)와 RPC 서버를 연결하는 MCP 서버 프로그램
5. ZCode MCP 등록       — 워크스페이스 설정으로 자동 연결

1.3 전체 아키텍처

flowchart LR
    subgraph ZCode["ZCode (AI 에이전트)"]
        AI[GLM 모델 에이전트]
    end

    subgraph MCP["MCP 서버 (stdio 프로세스)"]
        S["uvx freecad-mcp (PyPI 패키지 0.1.22)"]
    end

    subgraph FC["FreeCAD 1.1.3 (GUI 실행 중)"]
        ADDON["FreeCADMCP 애드온 RPC 서버 :9875"]
        DOC["문서 / 3D 모델"]
    end

    subgraph OUT["산출물"]
        STEP["STEP"]
        STL["STL"]
        DXF["DXF"]
        DWG["DWG"]
    end

    AI -- "MCP 도구 호출 (JSON-RPC over stdio)" --> S
    S -- "XML-RPC (localhost:9875)" --> ADDON
    ADDON -- "Python API (FreeCAD/App)" --> DOC
    DOC -- "execute_code로 내보내기" --> OUT
    ODA["ODA File Converter 27.1 (DWG↔DXF 자동 변환)"]
    ADDON -- "DWG 열기/저장 시 자동 호출" --> ODA
    ODA --> DXF
    ODA --> DWG

핵심은 MCP 서버는 "통역사"일 뿐이라는 점입니다. AI가 도구를 호출하면 → MCP 서버가 FreeCAD의 RPC 서버(9875)로 전달 → FreeCAD 내부에서 Python이 실행되는 구조입니다. 따라서 FreeCAD가 켜져 있지 않으면 MCP는 동작하지 않습니다. 반대로 켜져 있기만 하면 되고, 마우스·키보드는 전혀 점유하지 않습니다.

1.4 AI에게 명령하면 실제로 일어나는 일 (호출 시퀀스)

sequenceDiagram
    participant U as 사용자
    participant AI as ZCode AI
    participant M as freecad-mcp (stdio)
    participant F as FreeCAD (RPC :9875)

    U->>AI: "100×60×3mm 판에 M3 홀 4개 만들어줘"
    AI->>M: create_document(name="Case")
    M->>F: XML-RPC create_document
    F-->>M: 성공
    AI->>M: create_object(type="Part::Box", ...)
    M->>F: XML-RPC create_object
    F-->>M: Box 생성 (GUI에 표시)
    AI->>M: execute_code("M3 홀 4개 컷 + STEP 저장")
    M->>F: XML-RPC execute_code (Python 실행)
    F-->>M: 실행 결과 + 산출물 경로
    AI-->>U: 완료 보고 (파일 경로)

2. 설치 (이미 완료 — 재구축용 절차)

2.1 설치 흐름 요약

flowchart TD
    A[1. FreeCAD 1.1.3 설치 GitHub Releases 인스톨러] --> B[2. ODA File Converter 설치 opendesign.com MSI]
    B --> C[3. freecad-mcp 클론 후 애드온을 Mod 폴더에 복사]
    C --> D[4. 자동시작 + 가져오기 설정 JSON / 환경설정]
    D --> E[5. ZCode 워크스페이스 MCP 등록]
    E --> F[6. FreeCAD 실행 → 포트 9875 확인]
    F --> G[7. AI 제어 테스트]

2.2 세부 절차

① FreeCAD 1.1.3 설치

• https://github.com/FreeCAD/FreeCAD/releases 에서 FreeCAD_1.1.3-Windows-x86_64-py311-installer.exe 다운로드 (약 519MB, SHA256 서명 파일로 검증 권장)
• 무인 설치: FreeCAD_1.1.3-installer.exe /S — 단, /D=가 무시되어 항상 C:\Program Files\FreeCAD 1.1에 설치됨
• 다른 드라이브를 원하면 portable .7z 버전을 압축 해제해서 사용

② ODA File Converter 설치 (DWG 지원용)

• https://www.opendesign.com/guestfiles/oda_file_converter 에서 Windows 64bit MSI 다운로드 (무료, 등록 불필요)
• 설치: msiexec /i ODAFileConverter_QT6_vc16_amd64dll_27.1.msi /qn
• C:\Program Files\ODA\ODAFileConverter \ODAFileConverter.exe에 설치되면 FreeCAD가 자동으로 발견함 (별도 설정 불필요)

③ FreeCADMCP 애드온 설치 — ⚠️ 폴더 위치 주의

git clone https://github.com/neka-nat/freecad-mcp.git

• FreeCAD 1.1의 사용자 애드온 폴더는 %APPDATA%\FreeCAD\v1-1\Mod\ 다. (구버전 문서의 %APPDATA%\FreeCAD\Mod\가 아니라 버전 폴더(v1-1) 아래다 — 이것이 이번 설치에서 가장 큰 함정이었다)
• 저장소의 addon/FreeCADMCP 폴더 전체를 위 경로에 복사:

xcopy /E /I addon\FreeCADMCP "%APPDATA%\FreeCAD\v1-1\Mod\FreeCADMCP"

④ RPC 서버 자동시작 설정

%APPDATA%\FreeCAD\v1-1\freecad_mcp_settings.json 파일을 만든다:

{
  "remote_enabled": false,
  "allowed_ips": "127.0.0.1",
  "auto_start_rpc": true
}

• auto_start_rpc: true → FreeCAD를 켤 때마다 RPC 서버(포트 9875)가 자동 구동
• 수동으로도 가능: FreeCAD 워크벤치 목록에서 MCP Addon 선택 → FreeCAD MCP 툴바 → Start RPC Server

⑤ AI 모듈 설치

uvx freecad-mcp

• 첫 실행 시 Python 3.12와 의존성을 자동 다운로드(수십 초) 후 캐시됨
• 사전 요구: uv 설치 (pip install uv 또는 공식 인스톨러)

⑥ ZCode MCP 등록 (이 워크스페이스에는 이미 완료)

D:\AICAD\FREECAD\.zcode\config.json:

{
  "mcp": {
    "servers": {
      "freecad": {
        "command": "uvx",
        "args": ["freecad-mcp"]
      }
    }
  }
}

• 새 ZCode 세션을 열면 자동 연결되며, 도구 이름은 mcp__freecad__* 형태로 나타난다
• 다른 MCP 클라이언트에 등록할 때: Claude Desktop은 claude_desktop_config.json에 같은 command/args를, OpenCode는 opencode.json의 mcp 항목에 {"type":"local","command":["uvx","freecad-mcp"]}로 등록하면 된다

⑦ AI 자동화·한글 환경을 위한 환경설정 (이미 완료)

FreeCAD 기본값은 자동화에 방해되는 지점이 3개 있다. 아래를 실행해 한 번에 정리했다 (이 워크스페이스의 FreeCAD에는 적용 완료):

pg = App.ParamGet("User parameter:BaseApp/Preferences/Mod/Draft")
pg.SetBool("dxfShowDialog", False)        # DXF/DWG 가져오기 대화상자 끔 (자동화 필수)
pg.SetBool("dxfCreatePart", True)         # Part 형상으로 가져오기
pg.SetBool("dxfUseLegacyImporter", True)  # ★ 한글 경로 버그 회피 (아래 참고)
pg.SetBool("dxftext", True)               # 텍스트·치수 가져오기 (기본 False라 수치가 안 보임)
App.saveParameter()

• 한글 경로 버그: 모던(C++) DXF importer는 경로에 한글이 있으면 에러 없이 빈 문서를 만든다. 레거시 importer는 유니코드 경로 안전 → 위 설정이 필수다.
• 레거시 importer는 최초 사용 시 라이브러리 다운로드 확인창이 뜬다. "예"로 허용하면 이후 묻지 않는다 (dxfAllowDownload=True 저장됨).
• 레거시 방식은 대용량 도면에서 다소 느리다.

⑧ 탐색기에서 DWG 더블클릭으로 열기 (파일 연결)

레지스트리에 FreeCAD를 DWG 처리 프로그램으로 등록 (사용자 계정 범위, 관리자 불필요):

reg add "HKCU\Software\Classes\FreeCAD.DWG" /ve /d "FreeCAD DWG Drawing" /f
reg add "HKCU\Software\Classes\FreeCAD.DWG\DefaultIcon" /ve /d "C:\Program Files\FreeCAD 1.1\bin\FreeCAD.exe,0" /f
reg add "HKCU\Software\Classes\FreeCAD.DWG\shell\open\command" /ve /d "\"C:\Program Files\FreeCAD 1.1\bin\FreeCAD.exe\" \"%%1\"" /f
reg add "HKCU\Software\Classes\.dwg\OpenWithProgids" /v "FreeCAD.DWG" /d "" /f

(마지막 명령 파일이 아니라 배치에서 직접 칠 때는 %%1 → %1)

• 이후 Windows 정책상 1회 직접 선택이 필요: 탐색기에서 .dwg 우클릭 → 연결 프로그램 → 다른 앱 선택 → "FreeCAD DWG 도면" → "항상" 체크 → 확인
• 제거: reg delete "HKCU\Software\Classes\FreeCAD.DWG" /f
• 더블클릭으로 열린 DWG는 ⑦의 레거시 설정 덕에 한글 경로·한글 파일명도 정상으로 열린다

3. 사용 방법

3.1 매 사용 시 체크리스트 (단 2가지)

1. FreeCAD 실행 (바탕화면 아이콘 또는 C:\Program Files\FreeCAD 1.1\bin\FreeCAD.exe) — RPC 서버가 자동으로 함께 뜬다
2. ZCode에서 이 워크스페이스(D:\AICAD\FREECAD)로 세션 시작 — MCP 서버가 자동 연결됨

RPC 서버가 살아있는지 확인: netstat -an | findstr 9875

3.2 MCP 도구 15개

팁: 화면 변화가 없는 단순 계산·내보내기에는 include_screenshot: false를 쓰면 토큰이 절약된다.

3.3 ZCode에서 이런 식으로 명령한다

"100×60×3mm 알루미늄 판을 만들고 모서리에서 10mm 떨어진 곳에 M3 홀 4개를 뚫어줘"
→ create_document + create_object(Part::Box) + execute_code(구멍 컷)

"가운데 40×20mm 사각 구멍을 뚫고 모서리에 R3 필렛을 넣어줘"
→ execute_code (Part.makeBox + cut + makeFillet)

"이 모델을 STEP과 STL로 내보내줘"
→ execute_code (Part.export / MeshPart 테셀레이션 후 STL)

"이 도면을 DWG로 저장해줘"
→ execute_code (importDWG.convertToDwg) — ODA 변환기가 자동 호출됨

3.4 내보내기 정석 (발견된 함정 반영)

import Part, importDXF
obj = App.getDocument("MCP_Test").getObject("TestPlate")

Part.export([obj], r"D:\AICAD\FREECAD\out\model.step")   # STEP
importDXF.export([obj], r"D:\AICAD\FREECAD\out\model.dxf")  # DXF — 주의!

# STL은 바이너리 권장 (exportStl은 ASCII로 나와 용량이 5배 크다)
import MeshPart
m = MeshPart.meshFromShape(Shape=obj.Shape, LinearDeflection=0.1, AngularDeflection=0.3)
m.write(r"D:\AICAD\FREECAD\out\model.stl")

⚠️ DXF만 예외: Import.export([obj], "xxx.dxf")는 에러도 없이 아무 파일도 만들지 않는다. 반드시 importDXF.export를 사용할 것. (테스트에서 실제로 확인한 함정)

3.5 DWG 워크플로우

flowchart LR
    subgraph 받기["DWG 받아서 열기"]
        A["업체 DWG 파일"] --> B["FreeCAD 파일→열기 (또는 탐색기 더블클릭)"]
        B --> C{"ODA 자동 변환 DWG→DXF"}
        C --> D["FreeCAD로 가져오기 (대화상자 없이 자동)"]
    end

    subgraph 보내기["DWG로 내보내기"]
        E["FreeCAD 모델"] --> F["importDXF.export로 DXF"]
        F --> G["ODA CLI: DXF→DWG"]
        G --> H["업체 전달"]
    end

• 열기(권장 자동화 경로 — 실제 파일로 검증):

① ODA CLI로 DWG→DXF 변환:  ODAFileConverter.exe   ACAD2018 DXF 0 1
② FreeCAD에서 importDXF.open(변환된 .dxf)

• GUI에서는 파일→열기로 .dwg를 직접 열 수도 있다 (스크립트용 함수는 importDWG.open, 단 Import.open은 DWG를 모른다 — no supported file format 오류)
• 실전 검증: 2005년식 실제 업무 파일(2.2MB) → ODA 변환 후 1,917개 객체, 3,072×1,604mm 실스케일 복원. 한글 경로 파일은 반드시 레거시 importer(⑦ 설정)로.
• 내보내기(스크립트): importDWG.convertToDwg(dxf경로, dwg경로) 사용
• ODA CLI 직접 사용 시 (배치 변환 등):

ODAFileConverter.exe   ACAD2018 DWG 0 1

⚠️ 입력 폴더와 출력 폴더를 반드시 다르게 지정할 것. 같으면 "Output folder must be different than input folder" 에러 다이얼로그가 뜨고 프로세스가 멈춘다. (테스트에서 실제 확인)
⚠️ GUI 앱이라 셸에서 동기 실행하면 블록된다. 백그라운드 실행 + 출력 파일 폴링 권장.

3.6 도면 텍스트(수치) 표시

• dxftext=True 설정(⑦)으로 텍스트·치수·지시선이 함께 들어온다
• 가져온 텍스트에 {\f폰트명|...;\W1;338} 같은 MTEXT 서식 코드가 그대로 보이면: 텍스트 객체의 Text 속성에서 \로 시작해 ;로 끝나는 세그먼트를 제거하면 순수 수치만 남는다 (정리 루틴은 AGENTS.md #26 참고 — AI에게 "텍스트 정리해줘"라고 하면 된다)

3.7 확장 작업 — CNC G-code · 3D 프린팅

CNC 밀링/드릴 (Path 워크벤치, FreeCAD 기본 내장)

• 2.5D 가공 전반: 프로파일(외곽/내부 컷), 포켓, 드릴링, 엔그레이빙, 어댑티브 클리어링, 3D 표면 가공
• G-code 후처리기 내장: GRBL, Marlin, LinuxCNC, Mach3, Fanuc 등 — 컨트롤러에 맞는 G-code를 바로 출력
• 툴패스 시뮬레이터 내장 — 기계 돌리기 전 경로·충돌 검증
• 전부 Python API로 구동되므로 execute_code로 Job 생성 → 공구 지정 → 공정 배치 → 후처리(.nc)까지 자동화 가능

"이 하우징 외곽 컷팅하고 바닥 포켓 가공하는 G-code 만들어줘, 기계는 GRBL이야"
→ Path Job 생성 → Profile/Pocket 배치 → grbl_post 후처리 → .nc 파일

3D 프린팅 (FreeCAD = 모델링, 슬라이서 = G-code)

• FreeCAD는 모델링·STL까지만 담당 (§3.4의 바이너리 STL)
• G-code 생성은 슬라이서 영역 — Cura/PrusaSlicer/OrcaSlicer가 전부 CLI 모드를 제공하므로 AI가 직접 호출 가능
• 설계 수정이 잦은 제작업에 강한 이유: 치수 하나 바꾸면 모델→STL→G-code가 전부 재생성된다

"이 하우징을 PLA로 프린팅용 G-code 만들어줘, 0.4 노즐에 20% 인필"
→ STL 확인 → 슬라이서 CLI 실행 → .gcode 파일

flowchart LR
    M["FreeCAD 모델"] -->|"CNC"| P["Path Job (공구·공정 배치)"] --> G1["후처리기 GRBL 등"] --> NC[".nc G-code"]
    M -->|"3D 프린팅"| STL2["STL (바이너리)"] --> S["슬라이서 CLI Cura / OrcaSlicer"] --> G2[".gcode"]

⚠️ CNC 실가공 전 주의: 공구 직경·회전수·이송속도·원점·소재 고정은 기계 쪽 사용자 지식이 필요하다. AI는 파라미터를 넣으면 정확한 툴패스를 만들지만, 첫 가공은 반드시 시뮬레이션 → 에어컷 → 실컷 순서로 검증할 것. 3D 표면 가공은 2.5D 대비 정밀도 한계가 있다.

4. 문제해결 (트러블슈팅)

5. 테스트 결과 — 통합 10/10 PASS

상세 보고서: sample\TEST_REPORT.md / 데모 진행 기록: sample\DEMO_LOG.md

6. 샘플 데모 & 사용기 블로그

sample\ 폴더와 blog\ 폴더에 사용기 제작물이 들어 있다:

sample\
├── 컨트롤러_하우징.FCStd               ← 데모 원본 (330×170×30 외함 + 베젤 + 보스 + 케이블 슬롯)
├── controller_housing.step/.stl/.dxf   ← 내보낸 제조파일
├── screenshots\01~03_*.png             ← 단계별 화면 캡처
├── DEMO_LOG.md                          ← 명령별 진행 기록 (블로그 재료)
└── TEST_REPORT.md                       ← 통합 테스트 보고서

blog\
├── AI_FreeCAD_3D설계자동화_사용기.md   ← 매거진형 사용기 본문 (info/146 스타일)
└── AI_FreeCAD_사용기_배포.zip          ← 본문+이미지+첨부파일 배포 패키지

7. 다음 단계 — KiCad와의 연계

D:\AICAD\KICAD의 KiCad 환경과 연계하면:

1. KiCad(MCP)로 컨트롤러 기판 설계 → STEP으로 내보내기
2. FreeCAD(MCP)에서 기판 STEP을 불러와 캐비티 간섭검사·커버 설계 자동화
3. 보스 위치(15,15 / 305,15 / 15,145 / 305,145)에 맞춰 PCB 구멍 설계
4. STEP(가공업체), DXF(레이저 절단/판금), STL(3D 프린팅)로 출력

AI 작업 규칙과 발견 사항은 AGENTS.md에 기록되어 있다 — AI 에이전트는 작업 전 반드시 참고할 것.

8. 참고 자료

• FreeCAD 공식: https://www.freecad.org / 위키 DWG 문서: https://wiki.freecad.org/FreeCAD_and_DWG_Import
• FreeCAD 릴리스: https://github.com/FreeCAD/FreeCAD/releases
• ODA File Converter: https://www.opendesign.com/guestfiles/oda_file_converter
• freecad-mcp (neka-nat): https://github.com/neka-nat/freecad-mcp
• ZCode MCP 설정: 워크스페이스 .zcode/config.json → mcp.servers