Content
# Hueflow SketchUp MCP
> \\\*\\\*SketchUp을 Claude AI에 연결하는 MCP 서버 (한국어 / SketchUp 2024-2026 지원)\\\*\\\*
>
> 휴플로우 스튜디오의 인테리어 + AI 강의용으로 한국어화·재패키징한 버전입니다.
> Claude에게 "거실에 3x3x2.5m 방 만들어줘"라고 말하면 SketchUp이 실제로 모델을 만듭니다.
[!\[PyPI](https://img.shields.io/pypi/v/hueflow-sketchup-mcp)](https://pypi.org/project/hueflow-sketchup-mcp/)
\[!\[SketchUp](https://img.shields.io/badge/SketchUp-2024%20%7C%202025%20%7C%202026-orange)]()
[!\[License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
\---
## ⚠️ 시작하기 전에 — 꼭 확인하세요
### ✅ 필수 환경
* **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 페이지 가기**](https://github.com/hueflowstudio/hueflow-sketchup-mcp/releases/latest)
페이지 아래쪽 **"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을 **관리자 권한**으로 실행 후 다음 명령어 입력:
```powershell
winget install --id=astral-sh.uv -e
```
설치 완료 후 **컴퓨터 재부팅** (PATH 적용을 위해 필수).
확인 방법: PowerShell 새로 열어서:
```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. 설정 내용 입력
메모장에 아래 내용을 그대로 붙여넣기:
```json
{
"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에 없음.
**해결**:
```powershell
winget install --id=astral-sh.uv -e
```
설치 후 **반드시 컴퓨터 재부팅** (단순 PowerShell 재시작 안 됨).
### Q5. 설정 파일 수정했는데도 옛날 설정으로 떠요
**원인**: Claude Desktop이 백그라운드에 살아있어서 새 설정 안 읽음.
**해결**: PowerShell에서 강제 종료
```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**](https://github.com/Tarkiin/SketchUp-MCP) — 원본 코드 (MIT License)
* [**mhyrr/sketchup-mcp**](https://github.com/mhyrr/sketchup-mcp) — 최초 SketchUp MCP 컨셉 (MIT License)
한국어화 / 재패키징 © 2026 Hueflow Studio.
문의: [@hueflow\_studio](https://www.instagram.com/hueflow_studio/)
## 📜 라이선스
MIT License. 자세한 내용은 [LICENSE](LICENSE) 참조.
