AI 튜토리얼

3D Asset Server 튜토리얼: 18개 소스에서 게임 에셋 검색, 비교 및 다운로드

웹 UI, HTTP API, CLI 또는 MCP 통합을 통해 3d-asset-server를 설치하고 사용하는 방법을 알아보세요. 이 튜토리얼에서는 여러 제공업체 검색, 라이선스 확인, 형식 및 해상도 선택, 관련 파일 다운로드, 자체 호스팅 인스턴스 구성을 다룹니다.

2026년 10월 6일약 16분 소요

3D Asset Server 튜토리얼: 18개 소스에서 게임 에셋 검색, 비교 및 다운로드

3d-asset-server의 기능

3d-asset-server는 3D 모델, 머티리얼, 텍스처, HDRI, 스프라이트, UI 에셋, 오디오, 글꼴, 게임 에셋 팩을 한 곳에서 검색할 수 있는 검색창을 제공합니다. 18개 제공자를 검색하고 결과를 통합 및 순위화하며 각 소스의 상태를 표시하고, 제공자가 직접 다운로드를 허용하는 경우 에셋을 다운로드합니다.

브라우저, curl, 명령줄 인터페이스 또는 Model Context Protocol(MCP)을 통해 연결된 AI 어시스턴트에서 프로젝트를 사용할 수 있습니다. 결과에는 라이선스 정보, 가격 상태, 저작자 표시 요구 사항, 형식, 해상도 및 제공자 링크가 포함됩니다.

검색 작동 방식

각 쿼리에 대해 서버는 관련 제공자를 선택하고 병렬로 검색합니다. 제공자마다 자체 타임아웃이 적용되므로 느리거나 사용할 수 없는 사이트가 다른 소스의 결과 표시를 방해하지 않습니다.

결과 순위는 텍스트 관련성, 제공자의 순위, 결과가 API에서 제공되는지 스크래퍼에서 제공되는지 여부, 무료 이용 가능 여부, 직접 다운로드 지원 여부 및 소스 다양성을 기준으로 결정됩니다. 응답에는 ok, error, timeout, skipped, link와 같은 상태를 포함한 제공자별 보고서도 들어 있습니다.

일부 제공자는 직접 다운로드를 지원합니다. Poly Haven, ambientCG, Kenney, TextureCan 및 BlenderKit의 무료 에셋이 그 예입니다. 다른 제공자는 전체 메타데이터와 에셋 페이지 링크를 반환하며, Fab, Poliigon 및 TurboSquid는 봇 방지 기능으로 자동 검색이 차단될 때 자체 검색 페이지 링크를 제공합니다.

지원되는 소스

제공자 카탈로그에는 다양한 유형의 콘텐츠를 위한 소스가 포함되어 있습니다.

HDRI 및 PBR 머티리얼: Poly Haven, ambientCG, HDRMaps, HDRI Hub 및 3DTexel.
로우 폴리 및 게임 에셋: Kenney, Quaternius, Fab, itch.io 및 BlenderKit.
텍스처 및 스캔 머티리얼: CGBookcase, ShareTextures, TextureCan, Textures.com 및 3DTextures.me.
모델 및 에셋 마켓플레이스: BlenderKit, CGTrader, TurboSquid, Fab 및 itch.io.

라이선스 세부 정보는 목록마다 다릅니다. 예를 들어 Poly Haven, ambientCG 및 Kenney는 CC0 콘텐츠를 제공하지만, 마켓플레이스 제공자는 목록별 라이선스를 적용할 수 있습니다. 에셋을 배포하기 전에 반환된 라이선스 및 저작자 표시 정보를 항상 검토하세요.

설치 및 설정

이 프로젝트에는 Node.js 20 이상이 필요합니다. 저장소를 복제하고 종속 항목을 설치한 다음 애플리케이션을 빌드합니다.

git clone https://github.com/arielshad/3d-asset-server.git
cd 3d-asset-server
npm install
npm run build

다음 명령으로 웹 UI, HTTP API 및 MCP 엔드포인트를 시작합니다.

npm start

로컬 서버는 기본적으로 http://localhost:8787에서 실행됩니다.

Docker 설정

Docker를 사용해 서버를 빌드하고 실행할 수도 있습니다.

docker build -t 3d-asset-server .
docker run -p 8787:8787 3d-asset-server

웹 UI 사용

서버를 시작한 후 http://localhost:8787을 엽니다. 호스팅 버전은 3d.shep.bot에서 사용할 수 있습니다.

검색 페이지에서 쿼리를 입력하고 에셋 유형을 선택하거나, 결과를 무료 에셋으로 제한하거나, 직접 다운로드를 요구하거나, 특정 제공자를 선택할 수 있습니다. 검색 상태는 URL에 저장되므로 /search?q=sunset&type=hdri&free=true와 같은 쿼리를 북마크하거나 공유할 수 있습니다.

결과의 상세 시트를 열어 라이선스, 작성자, 형식, 폴리곤 수, 태그, 사용 가능한 해상도 및 예상 파일 크기를 확인합니다. 그런 다음 형식과 해상도를 선택하고 에셋을 다운로드하거나 curl 명령 또는 에이전트용 프롬프트를 복사할 수 있습니다.

호스팅 웹사이트는 문서, OpenAPI 참조, 소스 정보 및 자체 호스팅 안내도 제공합니다. 에이전트용 파일로는 /AGENTS.md, /llms.txt, /llms-full.txt 및 /openapi.json이 있습니다.

HTTP API로 검색

기본 검색 엔드포인트는 GET /v1/search입니다. 에셋 유형, 무료 이용 가능 여부, 직접 다운로드 지원 여부, 제공자, 결과 제한 수 및 오프셋과 같은 선택적 필터와 함께 쿼리를 제공합니다.

curl 'http://localhost:8787/v1/search?q=brick+wall&type=material&free=true&limit=5'

축약된 응답에는 순위가 지정된 결과와 제공자 보고서가 포함됩니다.

{
  "query": "brick wall",
  "results": [
    {
      "id": "polyhaven:brick_wall_001",
      "title": "Brick Wall 001",
      "type": "material",
      "license": {
        "name": "CC0",
        "commercialUse": true,
        "attributionRequired": false
      },
      "resolutions": ["1k", "2k", "4k", "8k"],
      "downloadable": true
    }
  ],
  "providers": [
    {
      "provider": "polyhaven",
      "status": "ok",
      "count": 5
    }
  ]
}

GET /v1/providers를 사용하면 제공자 카탈로그를 가져올 수 있고, GET /v1/assets/{provider}:{id}를 사용하면 전체 에셋 세부 정보를, GET /v1/assets/{id}/files를 사용하면 형식과 해상도로 선택한 파일을 확인할 수 있습니다.

API를 통한 다운로드

단일 파일 에셋의 경우 다운로드 엔드포인트가 소스 파일로 리디렉션합니다. 여러 파일로 구성된 에셋의 경우 에셋과 관련 파일이 포함된 zip을 스트리밍합니다.

curl -OJ 'http://localhost:8787/v1/assets/polyhaven:WoodenChair_01/download?format=gltf&resolution=1k'

API는 /health, /openapi.json, /v1/catalog 및 /v1/stats도 제공합니다. 카탈로그에는 제공자 및 에셋 수가 포함되며, 통계 엔드포인트는 사용량과 소스 상태를 보고합니다.

CLI 사용

빌드된 CLI는 HTTP 서버, 표준 입력 및 출력을 통한 MCP, 터미널 검색을 지원합니다.

node dist/cli.js search "low poly tree" --type model --free --limit 5

결과에는 점수, 에셋 유형, 무료 여부, 제공업체 식별자, 제목 및 소스 URL이 표시됩니다. 제공업체 상태는 결과 뒤에 출력되므로 어떤 사이트가 응답했는지, 어떤 사이트가 링크만 제공했는지 확인할 수 있습니다.

CLI에서 완전한 로컬 서비스를 실행하려면 다음을 사용하세요.

3d-asset-server serve

표준 입력 및 출력으로 MCP 서버를 시작하려면 다음을 사용하세요.

3d-asset-server mcp

AI 어시스턴트에서 MCP 사용하기

MCP를 사용하면 AI 어시스턴트가 에셋을 검색하고, 세부 정보를 확인하며, 허용된 파일을 다운로드할 수 있습니다. 사용 가능한 도구는 다음과 같습니다.

search_assets는 쿼리, 유형, 제공업체, 라이선스, 다운로드 가능 여부 및 페이지 매김 필터를 사용해 제공업체를 검색합니다.
get_asset은 메타데이터, 라이선스 정보, 사용 가능한 형식과 해상도, 그리고 선택한 다운로드에서 가져올 파일을 반환합니다.
download_asset은 에셋과 관련 파일을 구성된 디렉터리에 저장하고 지원되는 zip 팩의 압축을 풉니다.
list_providers는 모든 제공업체와 해당 에셋 유형, 가격, 라이선스 및 직접 다운로드 지원 여부를 설명합니다.

Claude Code

로컬 MCP 프로세스를 실행하고 현재 프로젝트의 에셋 디렉터리에 파일을 저장하도록 Claude Code를 구성하세요.

claude mcp add 3d-assets -e ASSET_DOWNLOAD_DIR="$PWD/assets" -- node /path/to/3d-asset-server/dist/cli.js mcp

Claude Desktop, Cursor 및 기타 Stdio 클라이언트

클라이언트의 MCP 구성에 서버 항목을 추가하세요.

{
  "mcpServers": {
    "3d-assets": {
      "command": "node",
      "args": ["/path/to/3d-asset-server/dist/cli.js", "mcp"],
      "env": {
        "ASSET_DOWNLOAD_DIR": "/path/to/your/game/assets"
      }
    }
  }
}

원격 MCP

호스팅된 서버는 Streamable HTTP MCP를 지원합니다.

claude mcp add --transport http 3d-assets https://3d.shep.bot/mcp

자체 호스팅 서버의 경우 클라이언트가 http://<host>:8787/mcp를 가리키도록 설정하세요. 원격 HTTP 다운로드는 기본적으로 비활성화되어 있습니다. 다운로드 시 서버 디스크에 파일이 저장되기 때문입니다. 이 모드에서 get_asset은 직접 파일 URL과 번들 zip URL을 반환합니다. 서버가 파일을 저장해야 하는 경우에만 ASSET_SERVER_HTTP_DOWNLOADS=true로 설정하세요.

다운로드 이해하기

형식을 지정하지 않으면 서버는 게임 및 웹에 실용적인 형식을 우선합니다. 모델은 glb, gltf, fbx, obj, blend 순으로 선호합니다. HDRI는 hdr를 우선하고 그 다음으로 exr를 사용합니다. 머티리얼은 이미지 맵 또는 zip을 우선하며, 텍스처는 jpg, png, zip, exr를 사용하고, 팩은 압축이 풀린 zip 파일로 다운로드됩니다.

기본 해상도는 사용 가능한 옵션 중 2K에 가장 가까운 해상도입니다. 관련 파일은 상대 경로를 유지하므로 glTF 파일이 별도의 재배치 없이 바이너리 및 텍스처 파일을 찾을 수 있습니다.

assets/
└── polyhaven-WoodenChair_01/
    ├── WoodenChair_01_2k.gltf
    ├── WoodenChair_01.bin
    └── textures/
        ├── WoodenChair_01_diff_2k.jpg
        ├── WoodenChair_01_nor_gl_2k.jpg
        └── WoodenChair_01_arm_2k.jpg

다운로더는 공개된 http 및 https URL만 가져오고, 비공개 주소와 루프백 주소는 거부하며, 구성 가능한 크기 제한을 적용하고, ../와 같은 안전하지 않은 아카이브 경로를 거부합니다. 로그인 페이지, 결제 절차 또는 핫링크 보호를 우회하지 않습니다.

구성

서버를 시작하기 전에 환경 변수를 설정하여 네트워크 주소, 제공업체, 다운로드, 보안 및 성능을 제어하세요.

PORT와 HOST는 HTTP 바인딩 주소를 제어합니다. 기본값은 각각 8787 및 0.0.0.0입니다.
ASSET_SERVER_PROVIDERS는 polyhaven,ambientcg,kenney와 같은 쉼표로 구분된 목록을 허용합니다.
ASSET_DOWNLOAD_DIR는 기본 MCP 다운로드 폴더인 ./assets를 변경합니다.
ASSET_SERVER_MAX_DOWNLOAD_BYTES는 다운로드당 크기 제한을 설정하며, 기본값은 2 GiB입니다.
ASSET_SERVER_PROVIDER_TIMEOUT_MS와 ASSET_SERVER_HTTP_TIMEOUT_MS는 제공업체 및 HTTP 타임아웃을 조정합니다.
ASSET_SERVER_CACHE_TTL_MS는 메모리 내 HTTP 캐시 유지 시간을 제어합니다.
BLENDERKIT_API_KEY를 사용하면 BlenderKit 요금제 및 구매한 에셋에 대한 접근을 활성화할 수 있습니다.
NODE_USE_ENV_PROXY=1로 설정하면 Node가 구성된 HTTPS_PROXY를 사용합니다.

인증 및 요청 제한

ASSET_SERVER_API_KEY를 설정하여 /v1/* 및 /mcp를 보호하세요. 클라이언트는 Bearer 토큰, x-api-key 헤더 또는 api_key 쿼리 매개변수로 키를 전송할 수 있습니다. 브라우저 기록과 서버 로그에 쿼리 매개변수가 포함될 수 있으므로 쿼리 매개변수 사용 시 주의하세요.

요청 제한은 기본적으로 60초 창마다 클라이언트당 120개 요청으로 활성화되어 있습니다. ASSET_SERVER_RATE_LIMIT 및 ASSET_SERVER_RATE_LIMIT_WINDOW를 구성하거나 제한을 0으로 설정하여 비활성화하세요.

프록시 및 제공업체 문제 해결

CGTrader는 클라우드 및 데이터센터 IP 주소를 차단할 수 있습니다. 가정용 인터넷 연결에서는 자주 작동하지만, 서버에서는 프록시를 구성하고 NODE_USE_ENV_PROXY=1로 설정하세요. 스크래핑된 제공업체의 HTML도 변경될 수 있습니다. 한 곳에 문제가 생겨도 다른 소스는 계속 결과를 반환하며, npm run test:live로 제공업체의 가용성을 확인할 수 있습니다.

고급 모니터링

별도의 포트에서 Prometheus 메트릭을 노출하려면 METRICS_PORT를 설정하세요. 서버는 검색, 제공자 요청, 다운로드, 에셋 조회, MCP 도구 호출, HTTP 요청 및 페이지 조회에 대해 제한된 라벨을 사용하는 메트릭을 기록합니다. 또한 IP 주소, 키 또는 쿠키를 기록하지 않고 구조화된 검색 이벤트를 로그에 남깁니다.

PROMETHEUS_URL이 구성된 경우 통계 엔드포인트에서 복제본 전체의 집계 데이터를 보고할 수 있습니다. 구성되지 않은 경우 통계는 마지막 재시작 이후 현재 프로세스의 데이터를 나타냅니다.

권장 워크플로

sunset, low poly tree 또는 brick wall과 같은 설명적인 검색어로 폭넓게 검색합니다.
에셋 유형, 무료 여부, 직접 다운로드 가능 여부 또는 선택한 제공자로 필터링합니다.
라이선스, 저작자 표시 요구 사항, 형식, 해상도 및 파일 목록을 확인합니다.
게임이나 웹사이트에 적합한 형식과 해상도를 선택합니다.
에셋을 다운로드하거나 제공자가 직접 다운로드를 허용하지 않는 경우 소스 링크를 복사합니다.
필요한 저작자 표시 및 라이선스 파일을 프로젝트와 함께 보관합니다.

결론

3d-asset-server는 분산된 에셋 탐색을 하나의 워크플로로 통합합니다. 웹 UI, HTTP API, CLI 및 MCP 도구를 사용하면 여러 제공자를 검색하고 라이선스 및 다운로드 정보를 비교하며 바로 사용할 수 있는 모델, 텍스처, HDRI 및 팩을 가져올 수 있습니다. Node.js 또는 Docker로 로컬에서 시작한 다음, 프로덕션 배포를 위해 제공자, 인증, 다운로드 경로, 속도 제한 및 모니터링을 구성하세요.