Poly.Pizza MCP Server

Poly.Pizza 3D 모델을 Unity 프로젝트에 바로 임포트할 수 있는 MCP (Model Context Protocol) 서버입니다.

주요 기능

모델 검색: 키워드로 Poly.Pizza에서 3D 모델 검색
Unity 임포트: 검색한 모델을 Unity 프로젝트에 자동 임포트
배치 임포트: 여러 모델을 한 번에 임포트
캐싱: 다운로드한 모델을 캐시하여 재사용
프리팹 자동 생성: 임포트된 모델에서 자동으로 Unity Prefab 생성
크레딧 자동 생성: CC-BY 라이선스 모델의 크레딧 자동 기록
Unity UI에서 API 키 설정: 환경 변수 없이 Unity 에디터에서 직접 API 키 입력 가능

요구사항

Node.js 18+
Unity 2019.4+
Poly.Pizza API Key

설치

1. Unity 패키지 설치 (Package Manager)

Unity에서 Window > Package Manager를 열고:

+ 버튼 클릭
Add package from git URL... 선택
다음 URL 입력:

https://github.com/HaD0Yun/poly-pizza-mcp.git?path=unity-package

2. MCP 서버 설치

git clone https://github.com/HaD0Yun/poly-pizza-mcp.git
cd poly-pizza-mcp
npm install
npm run build

3. API 키 설정 (Unity UI 사용 - 권장)

Unity에서 Window > Poly.Pizza MCP 또는 Poly.Pizza > Dashboard 메뉴 클릭
Get API Key 버튼을 클릭하여 poly.pizza/settings/api에서 API 키 발급
발급받은 API 키를 입력 필드에 붙여넣기
Save API Key 버튼 클릭

API 키는 ~/.poly-pizza/config.json에 저장되며, MCP 서버가 자동으로 읽어옵니다.

3-1. API 키 설정 (환경 변수 사용 - 대안)

환경 변수를 사용하려면:

# Windows
set POLY_PIZZA_API_KEY=your-api-key-here

# macOS/Linux
export POLY_PIZZA_API_KEY=your-api-key-here

4. MCP 클라이언트 설정

Claude Desktop 또는 다른 MCP 클라이언트의 설정 파일에 추가:

{
  "mcpServers": {
    "poly-pizza": {
      "command": "npx",
      "args": ["-y", "poly-pizza-mcp"],
      "env": {
        "UNITY_PROJECT_PATH": "/path/to/UnityProject"
      }
    }
  }
}

참고: API 키는 Unity Dashboard에서 설정했다면 env에 포함하지 않아도 됩니다.

사용 가능한 도구

`set_api_key`

API 키 설정 및 상태 확인

"API 키 상태 확인해줘"
→ set_api_key()

"API 키 설정해줘"
→ set_api_key(apiKey: "your-api-key")

"API 키 삭제해줘"
→ set_api_key(clear: true)

`search_models`

Poly.Pizza에서 모델 검색

"자동차 모델 찾아줘"
→ search_models(keyword: "car", limit: 10)

`import_to_unity`

특정 모델을 Unity로 임포트

"이 모델 Unity에 추가해줘: 5EGWBMpuXq"
→ import_to_unity(modelId: "5EGWBMpuXq", createPrefab: true)

`batch_import`

여러 모델을 한 번에 임포트

"이 모델들 전부 임포트해줘"
→ batch_import(modelIds: ["id1", "id2", "id3"])

`quick_import`

검색 후 첫 번째 결과 바로 임포트

"중세 검 모델 바로 넣어줘"
→ quick_import(query: "medieval sword")

`search_and_batch_import`

검색 결과 전체를 배치 임포트

"나무 모델 5개 찾아서 전부 임포트해"
→ search_and_batch_import(keyword: "tree", limit: 5)

`get_popular`

`cache_status`

캐시 상태 확인 및 관리

"캐시 상태 보여줘" → cache_status(action: "status")
"캐시 비워줘" → cache_status(action: "clear")

Unity 프로젝트 구조

MCP 서버가 모델을 임포트하면 다음 구조로 저장됩니다:

Assets/
└── PolyPizza/
    ├── Models/           # 3D 모델 파일 (.glb, .fbx 등)
    ├── Prefabs/          # 자동 생성된 프리팹
    ├── CREDITS.txt       # 라이선스 크레딧
    └── .signals/         # MCP ↔ Unity 통신용 (자동 관리)

Unity 메뉴

Unity Editor에서 사용할 수 있는 메뉴:

Window > Poly.Pizza MCP: API 키 설정 및 대시보드
Poly.Pizza > Dashboard: API 키 설정 및 상태 확인
Poly.Pizza > Refresh Assets: 에셋 새로고침
Poly.Pizza > Open Models Folder: 모델 폴더 열기
Poly.Pizza > Open Prefabs Folder: 프리팹 폴더 열기
Poly.Pizza > Create Prefabs from All Models: 모든 모델에서 프리팹 생성

라이선스 정보

Poly.Pizza의 모델은 두 가지 라이선스로 제공됩니다:

| 라이선스 | 저작자 표기 | 상업적 사용 | |---------|------------|------------| | CC0 | 불필요 | 가능 | | CC-BY | 필수 | 가능 |

CC-BY 라이선스 모델 사용 시 CREDITS.txt에 자동으로 크레딧이 기록됩니다. 게임 출시 시 크레딧 화면에 해당 내용을 포함해주세요.

개발

# 개발 모드 (watch)
npm run dev

# 빌드
npm run build

# 실행
npm start

문제 해결

API 키가 작동하지 않음

Unity에서 Poly.Pizza > Dashboard를 열고 API 키가 저장되어 있는지 확인
https://poly.pizza/settings/api 에서 키가 유효한지 확인
~/.poly-pizza/config.json 파일이 존재하고 API 키가 올바르게 저장되어 있는지 확인

Unity에서 모델이 보이지 않음

Unity Editor가 열려 있는지 확인
Assets > Refresh 또는 Poly.Pizza > Refresh Assets 실행
.signals 폴더의 파일이 처리되었는지 확인

캐시 문제

cache_status(action: "clear")로 캐시 초기화

License

MIT

Credits

Poly.Pizza - Free low poly 3D models
Created by dook (Zac Lucarelli)

MCP Servers