# 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) 참조.