FreeCAD + Opencode MCP 연동 가이드

이 문서는 유튜브 영상 “I Gave GPT-6 Astra Control of FreeCAD (It Designs Like an Engineer)” (M5KOgtk9VfI) 의 접근 방식을 기반으로, ChatGPT Desktop MCP 연동 방식을 Opencode(CLI 에이전트)에 그대로 이식하여 실무형 CAD 자동화 워크플로우로 정리한 가이드입니다.

1. 개요

영상의 핵심은 LLM이 MCP(Model Context Protocol)를 통해 FreeCAD를 직접 제어하는 방식입니다. LLM이 FreeCAD Python 코드를 생성하고, MCP 브릿지를 통해 FreeCAD에 전송하면 FreeCAD가 즉시 실행하며, 뷰포트 스냅샷을 피드백으로 받아 반복적으로 설계를 개선해 나가는 **시각적 피드백 루프(Observe → Generate → Execute → Verify)**를 구현합니다.

이 가이드는 동일한 FreeCAD MCP 서버(neeka-nat/freecad-mcp)를 Opencode에 연결하여, CLI 환경에서도 동일한 루프를 활용하되 작업 구조화, 파일/버전 관리, 검증 자동화 측면에서 실무에 더 적합하도록 최적화합니다.

2. 핵심 원리 (영상 요약)

핵심은 자연어 → FreeCAD Python API 실행 → 시각/상태 피드백 루프를 MCP로 표준화한 점입니다.

3. 아키텍처

Opencode는 MCP 클라이언트이므로, 영상에서 사용한 FreeCAD MCP 서버를 그대로 연결할 수 있습니다.

Opencode (CLI/TUI Agent)
  │
  ├─ MCP Client (stdio transport)
  │   └─ uvx freecad-mcp  (FreeCAD MCP Server, Python)
  │       └─ FreeCAD (GUI 권장 / Headless 선택)
  │            └─ FreeCAD Python API
  │                 ├─ Sketcher
  │                 ├─ PartDesign
  │                 ├─ Part / Body
  │                 └─ TechDraw (선택)
  │
  └─ 로컬 도구 병행
      ├─ Read/Edit/Glob/Grep  (코드/파일 검증)
      ├─ Bash                 (Export, 파일 확인, Git)
      └─ TodoWrite            (작업 구조화/진행 관리)

• 전송 방식: stdio (로컬 전용, 가장 단순하고 안정적)
• 실행 원리: FreeCAD가 사전에 실행 중이어야 MCP 서버가 FreeCAD와 연결/제어할 수 있습니다.
• 피드백 루프: MCP 툴 응답(문서 상태/스냅샷 등)을 기반으로 Opencode가 다음 액션을 스스로 결정합니다.

4. Opencode vs ChatGPT Desktop 비교

5. 사전 요구사항

중요 (Windows): uvx 설치 후 반드시 PowerShell을 완전 종료 후 재실행해야 PATH가 갱신됩니다. (영상 Step 3 참고)

6. 설치 절차

Step 1. ChatGPT Desktop 불필요 (Opencode 사용)

영상은 ChatGPT Desktop 전용이지만, 본 가이드는 Opencode를 사용하므로 Step 1의 ChatGPT Desktop 설치는 생략해도 됩니다.

Step 2. FreeCAD 설치

1. freecad.org에서 운영체제에 맞는 설치파일 다운로드
2. 설치 진행 (기본 설정 권장)
3. 설치 완료 후 FreeCAD 실행 가능 여부 확인

Step 3. uvx 설치 (Windows PowerShell, 관리자 권한)

1. Windows 시작 → PowerShell 검색 → 우클릭 → 관리자 권한으로 실행
2. 공식 설치 명령어 실행 (uv 설치 가이드 참조)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. PowerShell을 완전 종료한 뒤, 다시 관리자 권한으로 실행
4. 설치 확인

uvx --version

버전이 정상적으로 출력되면 설치 성공입니다.

Step 4. FreeCAD MCP 애드온 설치

1. freecad-mcp GitHub → Code → Download ZIP 다운로드
2. ZIP 압축 해제
3. 압축 해제 폴더 내부의 FreeCAD-MCP/ (또는 저장소 루트의 MCP 관련 애드온 폴더)를 FreeCAD Mod 경로에 복사

FreeCAD Mod 경로 (Windows)

%APPDATA%\FreeCAD\1.1\Mod\

실행 방법: Win + R → %APPDATA%\FreeCAD\1.1\Mod\ 입력 → Enter

• 해당 폴더에 FreeCAD-MCP/ 폴더를 통째로 붙여넣기
• Mod/ 폴더에 mod가 없으면 새로 생성
• FreeCAD 버전 < 1.1인 경우: 버전 하위폴더(1.1/)가 아닌 **FreeCAD 루트의 Mod/**에 복사 (영상 설명 준수)

4. FreeCAD를 완전 재시작
5. FreeCAD 상단 Workbench 드롭다운에서 MCP 항목이 나타나는지 확인 → 설치 완료

Step 5. Opencode MCP 서버 설정

Opencode는 .opencode/mcp.json 파일을 통해 MCP 서버를 등록합니다. 프로젝트 루트 또는 전역(~/.config/opencode/ 또는 Windows 환경에 맞게) 설정 가능합니다. 프로젝트별로 고정하는 걸 권장합니다.

워크스페이스 루트(또는 원하는 위치)에 .opencode/mcp.json 생성

{
  "mcpServers": {
    "freecad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["freecad-mcp"],
      "timeout": 120000
    }
  }
}

설정 옵션 설명

로컬 소스 수정본 사용 시 (선택)

FreeCAD MCP를 커스텀/수정해서 사용하고 싶다면 아래와 같이 경로를 지정할 수 있습니다.

{
  "mcpServers": {
    "freecad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "C:/path/to/freecad-mcp", "freecad-mcp"],
      "timeout": 120000
    }
  }
}

Step 6. 연결 확인

1. FreeCAD를 먼저 실행 (GUI 모드 권장)
2. Opencode를 실행 (opencode CLI)
3. 대화에서 간단한 테스트 프롬프트를 입력

FreeCAD에 빈 문서를 하나 만들고, Body를 생성한 뒤 "MCP 연결 테스트"라는 이름의 Sketch를 추가해줘.

4. Opencode가 freecad MCP 툴을 호출하고, FreeCAD에서 문서/오브젝트가 생성되면 연결이 정상입니다.

7. 권장 워크플로우 (엔지니어링 관점)

영상의 "Designs Like an Engineer(엔지니어처럼 설계)"를 실현하려면 파라메트릭(Parametric) + 히스토리 기반(Feature History) 설계를 고정하는 게 가장 중요합니다.

7.1 설계 원칙 (Best Practices)

7.2 Opencode 작업 구조화 (TodoWrite)

Opencode의 가장 큰 강점은 **TodoWrite**를 통한 다단계 작업 관리입니다. 복잡한 3D 모델링은 반드시 작업을 세분화해 in_progress를 1개로 유지하는 걸 권장합니다.

권장 Todo 템플릿 (일반적인 파트 모델링)

1. [pending] 요구사항 정리 및 설계 방향 수립 (치수/목적/제약 조건)
2. [pending] FreeCAD 문서 생성 및 Body/Part 구조 설정
3. [pending] 스케치(Sketch) 작성 및 구속(Constraints) 적용 (Fully Constrained)
4. [pending] 1차 피처 생성 (Pad/Extrude 등)
5. [pending] 추가 피처 (Pocket/Hole/Chamfer/Fillet/Round)
6. [pending] 형상 검증 (치수/대칭/간섭 체크, 뷰포트 확인)
7. [pending] 치수/볼륨 측정 기반 수치 검증
8. [pending] Export (.FCStd + .STEP) + 파일 존재/유효성 확인
9. [pending] 최종 검토 및 정리

Opencode는 작업 진행 중 이 Todo 리스트를 실시간으로 업데이트하므로, 대화가 길어져도 컨텍스트/방향성을 잃지 않고 일관된 흐름으로 작업을 완료할 수 있습니다.

7.3 GUI vs Headless 선택

권장: 설계 품질/정확도 검증을 중시한다면 항상 FreeCAD GUI를 먼저 실행한 상태에서 Opencode를 사용하는 구성을 권장합니다.

7.4 안정성/신뢰성 팁

8. 트러블슈팅

9. 결론

권장 구성: Opencode + uvx freecad-mcp (stdio) + FreeCAD GUI (사전 실행)

• 영상에서 제시한 MCP 패턴은 그대로 유지하면서,
• Opencode 고유의 **TodoWrite(계획/진행 관리) + 로컬 도구(Bash/Grep/Read/Edit) + Git 연계(버전관리)**를 결합하면 단순 생성형 CAD를 넘어 설계 → 검증 → 산출물 관리가 닫힌 엔지니어링 워크플로우로 확장할 수 있습니다.
• 실무 적용 시 핵심 원칙은 Sketcher+PartDesign 우선 (파라메트릭 히스토리 유지), Fully Constrained, 측정값 기반 검증, .FCStd + .STEP 동시 Export입니다.

간단히 요약하면, ChatGPT Desktop 대비 Opencode 조합이 실무형 CAD 자동화/버전관리 측면에서 훨씬 더 적합한 구성입니다.