メインコンテンツへ移動
AIチュートリアル

3Dアセットサーバーチュートリアル：18のソースからゲームアセットを検索・比較・ダウンロード

Web UI、HTTP API、CLI、MCP統合を通じて3d-asset-serverをインストールし、使用する方法を学びます。このチュートリアルでは、複数のプロバイダーの検索、ライセンスの確認、形式と解像度の選択、関連ファイルのダウンロード、セルフホスト環境の設定について説明します。

約18分で読了
3Dアセットサーバーチュートリアル：18のソースからゲームアセットを検索・比較・ダウンロード

3d-asset-serverの機能

3d-asset-serverは、3Dモデル、マテリアル、テクスチャ、HDRI、スプライト、UIアセット、音声、フォント、ゲームアセットパックを1つの検索ボックスで検索できます。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

次のコマンドでWeb 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

Web UIの使用

サーバーの起動後、http://localhost:8787を開きます。ホスト版は3d.shep.botで利用できます。

検索ページでクエリを入力し、アセットの種類を選択します。無料アセットに限定したり、直接ダウンロードを必須にしたり、特定のプロバイダーを選択したりすることもできます。検索状態はURLに保存されるため、/search?q=sunset&type=hdri&free=trueのようなクエリをブックマークしたり共有したりできます。

結果の詳細シートを開くと、ライセンス、作者、形式、ポリゴン数、タグ、利用可能な解像度、推定ファイルサイズを確認できます。その後、形式と解像度を選択してアセットをダウンロードしたり、curlコマンドやエージェント向けプロンプトをコピーしたりできます。

ホスト版Webサイトでは、ドキュメント、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

Claude CodeがローカルMCPプロセスを起動し、現在のプロジェクトのアセットディレクトリにファイルを保存するよう設定します。

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を設定してください。

ダウンロードについて

形式を指定しない場合、サーバーはゲームやWebで実用的な形式を優先します。モデルは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を使用します。

認証とレート制限

/v1/*と/mcpを保護するには、ASSET_SERVER_API_KEYを設定します。クライアントは、Bearerトークン、x-api-keyヘッダー、またはapi_keyクエリパラメーターとしてキーを送信できます。ブラウザー履歴やサーバーログにキーが含まれる可能性があるため、クエリパラメーターの使用には注意してください。

レート制限はデフォルトで有効になっており、60秒間にクライアント1つあたり120リクエストです。ASSET_SERVER_RATE_LIMITとASSET_SERVER_RATE_LIMIT_WINDOWを設定するか、制限を0にして無効にできます。

プロキシとプロバイダーのトラブルシューティング

CGTraderはクラウドやデータセンターのIPアドレスをブロックすることがあります。自宅の接続からは動作することが多く、サーバー上ではプロキシを設定し、NODE_USE_ENV_PROXY=1を指定してください。スクレイピング対象のプロバイダーはHTMLを変更することもあります。1つのプロバイダーが動作しなくなっても、他のソースは引き続き結果を返します。また、npm run test:liveでプロバイダーの利用可能性を確認できます。

高度な監視

Prometheusメトリクスを別ポートで公開するには、METRICS_PORTを設定します。サーバーは、検索、プロバイダーへのリクエスト、ダウンロード、アセット表示、MCPツール呼び出し、HTTPリクエスト、ページビューについて、ラベル数に上限を設けたメトリクスを記録します。また、IPアドレス、キー、Cookieを記録せずに、構造化された検索イベントをログに出力します。

PROMETHEUS_URLを設定すると、統計エンドポイントでレプリカ全体の集計データを報告できます。設定しない場合、統計には直近の再起動以降に現在のプロセスで収集されたデータが表示されます。

推奨ワークフロー

  1. sunset、low poly tree、brick wallなど、説明的なクエリで幅広く検索します。
  2. アセットの種類、無料かどうか、直接ダウンロードの可否、または選択したプロバイダーで絞り込みます。
  3. ライセンス、帰属表示の要件、形式、解像度、ファイル一覧を確認します。
  4. ゲームやウェブサイトに適した形式と解像度を選択します。
  5. アセットをダウンロードするか、プロバイダーが直接ダウンロードを許可していない場合はソースリンクをコピーします。
  6. 必要な帰属表示とライセンスファイルをプロジェクトと一緒に保管します。

まとめ

3d-asset-serverは、分散したアセット検索を1つのワークフローにまとめます。ウェブUI、HTTP API、CLI、MCPツールを使って、多数のプロバイダーを検索し、ライセンスやダウンロード情報を比較し、すぐに使えるモデル、テクスチャ、HDRI、パックを取得できます。Node.jsまたはDockerでローカル環境から始め、プロダクション環境へのデプロイに向けて、プロバイダー、認証、ダウンロードパス、レート制限、監視を設定してください。