가이드Sozai Search MCP중급약 10분7단계
Claude Code에 무료 3D 에셋 3만 9천 개 도서관 붙이기: Sozai Search MCP
3D 에셋을 자주 찾는 크리에이터와 개발자를 위한 중급 가이드입니다. Claude Code에 Sozai Search를 연결해 모델 검색부터 내려받기까지 해 봅니다.
시작하기 전에
- Claude Code 설치(Codex, Claude Desktop, Cursor도 같은 서버 사용 가능)
- 터미널과 3D 파일을 받을 프로젝트 폴더
- uv(없으면 가이드에서 설치), uv가 Python 3.10 이상을 가져옴
- 공개 데이터용 디스크 약 15MB, 선택 기능인 의미 검색용 약 600MB 추가
터미널에서 uv --version을 실행하세요. uv를 찾을 수 없다고 나오면 사용 중인 시스템에 맞는 명령어로 설치합니다. Windows는 PowerShell 명령어를 쓰세요.
터미널에서 실행 uv --versionuv가 없을 때만 아래 명령어를 터미널에서 실행하세요. Windows에서는 README의 PowerShell 명령어를 대신 실행합니다.
터미널에서 실행 curl -LsSf https://astral.sh/uv/install.sh | sh본인 프로젝트 폴더에서 터미널을 열고 아래 Claude Code 명령어를 실행하세요. 저장소를 clone할 필요는 없고, uv가 GitHub에서 Sozai Search를 가져옵니다. 이 프로젝트 전용 .mcp.json이 만들어집니다.
터미널에서 실행 claude mcp add sozai -s project -- uvx --from git+https://github.com/kanaworksai-hue/sozai-search-mcp sozaiMCP 서버는 세션이 시작될 때 불러오므로 프로젝트에서 Claude Code 새 세션을 여세요. 프로젝트의 .mcp.json을 승인하라는 안내가 한 번 나옵니다. 이어서 서버 목록에 sozai가 있는지 확인하세요.
터미널에서 실행 claude mcp list아래 내용을 Claude에 붙여 넣어 모델을 요청하세요. 첫 검색에서 공개 데이터(약 15MB)를 내려받고 몇 초 만에 색인을 만듭니다. fetch 도구는 프로젝트 안의 절대 경로 폴더가 필요하므로 폴더를 지정해야 합니다.
Claude에 붙여넣기 Search Sozai for a wooden crate under 1 m tall, look at the previews, pick the best one, and fetch it into an assets folder inside this project (use the absolute path).뜻: 높이 1m 미만의 나무 상자를 Sozai에서 찾아 미리보기를 비교한 뒤, 가장 좋은 것을 프로젝트 안 assets 폴더에 절대 경로로 내려받으라는 지시입니다.
의미 검색을 켜면 설명형 질문과 다른 언어 질문의 결과가 크게 좋아집니다. 원문 테스트에서 맞는 에셋이 1순위로 나온 비율은 31%에서 79%였습니다. 디스크를 한 번 약 600MB 쓰므로 원할 때만 켜고, 먼저 아래 명령어로 질의 모델을 내려받으세요.
터미널에서 실행 uvx --from "sozai-search-mcp[semantic] @ git+https://github.com/kanaworksai-hue/sozai-search-mcp" sozai semantic-setup서버를 다시 등록하되, --from 값을 의미 검색용 값으로 바꿉니다. 아래 명령어에 이미 바뀐 값이 들어 있습니다.
터미널에서 실행문서를 바탕으로 구성한 예시 claude mcp add sozai -s project -- uvx --from "sozai-search-mcp[semantic] @ git+https://github.com/kanaworksai-hue/sozai-search-mcp" sozai
주의할 점
- MCP 서버는 세션을 시작할 때만 불러오므로, 등록한 뒤에는 새 세션을 여세요.
- Sozai Search는 색인일 뿐 에셋 파일을 보관하지 않아, Poly Haven, ambientCG 같은 공식 출처에서 내 컴퓨터가 직접 받습니다.
- fetch 도구에는 프로젝트 안의 절대 경로 폴더를 주세요. 경로는 지정한 폴더 안에 머뭅니다.
- 대부분 CC0이지만 전부는 아닙니다. redistributable_only 옵션으로 배포 가능한 것만 남기고, 출처는 CREDITS.md에 추가됩니다.
- Windows에서는 curl 명령어 대신 README의 PowerShell 명령어로 uv를 설치하세요.
자주 묻는 질문
- Claude Code 말고 다른 도구에서도 되나요?
- 됩니다. Codex는 codex mcp add 명령어가 따로 있고, Claude Desktop과 Cursor 등 다른 MCP 클라이언트는 JSON 설정에 같은 서버 명령어를 넣습니다.
- 어떤 결과물을 받나요?
- 모델마다 .glb 파일 하나, PBR 폴더, HDRI, CREDITS.md를 받습니다. Kit 모델은 미터 단위 실제 크기(문 2.1m, 사람 1.75m)에 맞춰 보정되어 이미 스케일이 적용된 상태로 옵니다.
- 무겁지 않나요?
- 무겁지 않습니다. 서버는 런타임 의존성이 없는 표준 라이브러리 Python이고, 시작에 약 25ms, 유휴 시 메모리 약 23MB를 씁니다.
- 내 파일을 삭제할 수도 있나요?
- README는 파일을 삭제하지 않고, 각 라이브러리의 공식 호스트에만 https로 접속하며, 모든 경로를 지정한 폴더 안에 둔다고 밝힙니다.