Young Tries AI

Claude Code에 무료 3D 에셋 3만 9천 개 도서관 붙이기: Sozai Search MCP

3D 에셋을 자주 찾는 크리에이터와 개발자를 위한 중급 가이드입니다. Claude Code에 Sozai Search를 연결해 모델 검색부터 내려받기까지 해 봅니다.

스킬·MCP대상: 크리에이터, 개발자

시작하기 전에

  • Claude Code 설치(Codex, Claude Desktop, Cursor도 같은 서버 사용 가능)
  • 터미널과 3D 파일을 받을 프로젝트 폴더
  • uv(없으면 가이드에서 설치), uv가 Python 3.10 이상을 가져옴
  • 공개 데이터용 디스크 약 15MB, 선택 기능인 의미 검색용 약 600MB 추가
  1. 터미널에서 uv --version을 실행하세요. uv를 찾을 수 없다고 나오면 사용 중인 시스템에 맞는 명령어로 설치합니다. Windows는 PowerShell 명령어를 쓰세요.

    터미널에서 실행
    uv --version
  2. uv가 없을 때만 아래 명령어를 터미널에서 실행하세요. Windows에서는 README의 PowerShell 명령어를 대신 실행합니다.

    터미널에서 실행
    curl -LsSf https://astral.sh/uv/install.sh | sh
  3. 본인 프로젝트 폴더에서 터미널을 열고 아래 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 sozai
  4. MCP 서버는 세션이 시작될 때 불러오므로 프로젝트에서 Claude Code 새 세션을 여세요. 프로젝트의 .mcp.json을 승인하라는 안내가 한 번 나옵니다. 이어서 서버 목록에 sozai가 있는지 확인하세요.

    터미널에서 실행
    claude mcp list
  5. 아래 내용을 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 폴더에 절대 경로로 내려받으라는 지시입니다.

  6. 의미 검색을 켜면 설명형 질문과 다른 언어 질문의 결과가 크게 좋아집니다. 원문 테스트에서 맞는 에셋이 1순위로 나온 비율은 31%에서 79%였습니다. 디스크를 한 번 약 600MB 쓰므로 원할 때만 켜고, 먼저 아래 명령어로 질의 모델을 내려받으세요.

    터미널에서 실행
    uvx --from "sozai-search-mcp[semantic] @ git+https://github.com/kanaworksai-hue/sozai-search-mcp" sozai semantic-setup
  7. 서버를 다시 등록하되, --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로 접속하며, 모든 경로를 지정한 폴더 안에 둔다고 밝힙니다.

출처