Hueflow SketchUp MCP

\*\*SketchUp을 Claude AI에 연결하는 MCP 서버 (한국어 / SketchUp 2024-2026 지원)\*\*

휴플로우 스튜디오의 인테리어 + AI 강의용으로 한국어화·재패키징한 버전입니다. Claude에게 "거실에 3x3x2.5m 방 만들어줘"라고 말하면 SketchUp이 실제로 모델을 만듭니다.

 []() 

---

⚠️ 시작하기 전에 — 꼭 확인하세요

✅ 필수 환경

• SketchUp Pro 데스크탑 버전 (2024 / 2025 / 2026 중 하나)
• Claude Desktop 앱 ← 웹 브라우저 버전(claude.ai)에서는 절대 안 됩니다
• Windows 또는 macOS

🚫 안 되는 환경

• ❌ SketchUp Free (브라우저 웹 버전)
• ❌ Claude.ai 웹 브라우저 버전
• ❌ SketchUp 2023 이하 (검증 안 됨)

---

⚡ 빠른 설치 (4단계)

1️⃣ SketchUp 플러그인 설치 (.rbz)

1-1. .rbz 파일 다운로드

👉 Releases 페이지 가기

페이지 아래쪽 "Assets" 섹션에서 hueflow\\\_sketchup\\\_mcp.rbz 클릭해서 다운로드.

💡 \*\*.rbz 파일이란?\*\* SketchUp 전용 플러그인 설치 파일이에요. ZIP 압축 형식으로, SketchUp이 자동으로 인식하고 설치해줍니다. 압축 풀거나 별도 폴더에 옮기지 마세요.

1-2. SketchUp에 설치

1. SketchUp 실행
2. 상단 메뉴: 창(Window) → 확장 관리자(Extension Manager)
3. 좌측 하단 확장 설치(Install Extension) 버튼 클릭
4. 다운받은 hueflow\\\_sketchup\\\_mcp.rbz 파일 선택 → 열기
5. "이 확장은 디지털 서명되지 않았습니다" 경고 뜨면 예 클릭
6. 설치 완료 후 SketchUp 완전 종료 후 재시작

1-3. 설치 확인

SketchUp 재시작 후 상단 메뉴에서 확인:

확장(Plugins) → Hueflow MCP 서버

서브메뉴에 4개 항목이 보이면 성공:

• 서버 시작
• 서버 중지
• 서버 재시작
• 서버 상태 확인

---

2️⃣ Claude Desktop 앱 설치 + 설정

2-1. Claude Desktop 앱 설치

⚠️ 웹 브라우저 버전(claude.ai)이 아닌, 데스크탑 앱이 필요합니다.

다운로드: https://claude.ai/download

설치 후 컴퓨터를 재부팅하세요. 재부팅해야 설정 폴더가 정상 생성됩니다.

2-2. uv 설치 (Python 패키지 매니저)

PowerShell을 관리자 권한으로 실행 후 다음 명령어 입력:

winget install --id=astral-sh.uv -e

설치 완료 후 컴퓨터 재부팅 (PATH 적용을 위해 필수).

확인 방법: PowerShell 새로 열어서:

where.exe uv

경로가 나오면 OK. 안 나오면 재부팅 다시.

2-3. Claude Desktop 설정 파일 만들기

⚠️ 중요: Claude Desktop을 처음 설치하면 설정 파일(claude\\\_desktop\\\_config.json)이 자동으로 생성되지 않을 수 있습니다. 두 가지 방법 중 하나로 만드세요:

방법 A — Claude Desktop에서 자동 생성 (권장)

1. Claude Desktop 실행 + 로그인
2. 좌측 상단 메뉴(≡) → 설정(Settings) 클릭 (또는 Ctrl+,)
3. 좌측 메뉴에서 개발자(Developer) 클릭
4. 구성 편집(Edit Config) 버튼 클릭
5. 메모장이 자동으로 열림 (빈 파일 또는 기본 내용)

방법 B — 직접 만들기

1. 윈도우 키 + R → 입력: %APPDATA%\\\\Claude → 엔터
2. 폴더가 안 보이면 → Claude Desktop 한 번 실행하고 종료 후 다시 시도
3. 빈 곳 우클릭 → 새로 만들기 → 텍스트 문서
4. 파일 이름을 claude\\\_desktop\\\_config.json 으로 변경 (확장자 .txt 빼야 함)
5. 우클릭 → 메모장으로 열기

2-4. 설정 내용 입력

메모장에 아래 내용을 그대로 붙여넣기:

{
  "mcpServers": {
    "hueflow-sketchup": {
      "command": "uvx",
      "args": \\\["hueflow-sketchup-mcp"]
    }
  }
}

Ctrl+S로 저장 → 메모장 닫기

---

3️⃣ 실행 — 순서가 매우 중요!

⚠️ 반드시 이 순서를 지키세요. 안 그러면 연결이 안 됩니다.

3-1. Claude Desktop 완전 종료

작업표시줄 우측 화살표(⌃) → Claude 아이콘 우클릭 → Quit

단순히 X 버튼으로 닫으면 백그라운드에 남아있어서 안 됩니다. 완전 종료 필수.

3-2. SketchUp 먼저 실행

1. SketchUp 실행
2. 상단 메뉴: 확장(Plugins) → Hueflow MCP 서버 → 서버 시작
3. 다시 확장 → Hueflow MCP 서버 → 서버 상태 확인
4. ✅ Hueflow MCP 서버 작동 중 / 포트: 8080 메시지 확인

💡 보통 SketchUp 시작과 동시에 서버가 자동으로 켜집니다. 안 켜졌으면 수동으로 시작.

3-3. Claude Desktop 다시 실행

이제 Claude Desktop을 시작 메뉴에서 다시 실행.

3-4. 연결 확인

설정 → 개발자 → MCP 서버 목록에서 hueflow-sketchup 옆에 running 표시 확인.

3-5. 첫 명령

새 채팅 시작하고 입력:

스케치업 모델 정보 알려줘

도구 사용 권한 팝업 → 이 채팅에서만 허용

Claude가 진짜 SketchUp 정보를 가져오면 🎉 성공!

---

🎯 할 수 있는 것 (21가지 도구)

분류	명령 예시
모델 정보	"현재 모델에 어떤 컴포넌트들 있어?"
박스 생성	"1.2x0.6x0.75m 책상 만들어줘"
원/호	"반지름 50cm 원 그려줘"
푸시풀	"이 면 1m 밀어줘"
재질 적용	"벽에 흰색 페인트 칠해줘"
이동/회전/스케일	"그 컴포넌트 90도 돌려줘"
지붕 트러스	"8m 폭에 킹포스트 트러스 만들어줘"
Ruby 코드 실행	고급 사용자용

---

🩺 자주 막히는 부분 (FAQ)

Q1. "SketchUp에 연결할 수 없습니다" 에러

원인: 실행 순서가 틀렸을 가능성 큼.

해결:

1. Claude Desktop 완전 종료 (작업관리자에서 Claude 프로세스 다 죽이기)
2. SketchUp 먼저 켜고 서버 작동 확인
3. 그 다음 Claude Desktop 실행

Q2. %APPDATA%\\\\Claude 폴더에 들어갔는데 claude\\\_desktop\\\_config.json 파일이 없어요

원인: Claude Desktop을 처음 설치했거나, 설정을 한 번도 변경한 적 없음.

해결: 위 2-3 방법 A (구성 편집 버튼)로 자동 생성하거나, 방법 B로 직접 만들기.

Q3. Claude 폴더 자체가 없어요

원인: Claude Desktop을 한 번도 실행 안 했거나, 설치 후 재부팅 안 함.

해결: Claude Desktop 한 번 실행 → 로그인 → 종료 → 컴퓨터 재부팅 → 다시 폴더 확인.

Q4. "uvx를 찾을 수 없습니다" 에러

원인: uv가 설치 안 됐거나 PATH에 없음.

해결:

winget install --id=astral-sh.uv -e

설치 후 반드시 컴퓨터 재부팅 (단순 PowerShell 재시작 안 됨).

Q5. 설정 파일 수정했는데도 옛날 설정으로 떠요

원인: Claude Desktop이 백그라운드에 살아있어서 새 설정 안 읽음.

해결: PowerShell에서 강제 종료

Stop-Process -Name "Claude" -Force -ErrorAction SilentlyContinue

그 다음 Claude Desktop 다시 실행.

Q6. Claude 웹 브라우저 버전(claude.ai)에서 작동시킬 수 있나요?

아니요. MCP 기능은 Claude Desktop 앱 전용입니다. claude.ai 웹사이트에서는 절대 작동하지 않습니다.

Q7. 플러그인이 SketchUp에 안 보여요

해결:

1. 확장 관리자에서 활성화 상태 확인
2. SketchUp 완전 종료 후 재시작
3. Ruby 콘솔(창 → Ruby 콘솔)에서 에러 메시지 확인

Q8. "Port 8080 already in use" 에러

원인: 다른 프로그램이 포트 8080 사용 중. 보통 다른 SketchUp이 백그라운드에 있는 경우.

해결:

1. 작업관리자에서 SketchUp 프로세스 다 종료
2. 다시 SketchUp 한 개만 실행

Q9. 디버그 로그 위치

• Windows: %TEMP%\\\\sketchup\\\_mcp\\\_debug.log
• macOS: /tmp/sketchup\\\_mcp\\\_debug.log

---

🙏 크레딧

이 프로젝트는 다음 오픈소스 프로젝트를 기반으로 합니다:

• Tarkiin/SketchUp-MCP — 원본 코드 (MIT License)
• mhyrr/sketchup-mcp — 최초 SketchUp MCP 컨셉 (MIT License)

한국어화 / 재패키징 © 2026 Hueflow Studio.

문의: @hueflow_studio

📜 라이선스

MIT License. 자세한 내용은 LICENSE 참조.