3D Asset Server Tutorial: Search, Compare, and Download Game Assets from 18 Sources

What 3d-asset-server Does

3d-asset-server provides one search box for 3D models, materials, textures, HDRIs, sprites, UI assets, audio, fonts, and game asset packs. It searches 18 providers, merges and ranks the results, reports the status of each source, and downloads assets when the provider permits direct downloads.

You can use the project from a browser, with curl, through its command-line interface, or from an AI assistant connected through the Model Context Protocol (MCP). Results include licence information, pricing status, attribution requirements, formats, resolutions, and provider links.

How Searches Work

For each query, the server selects relevant providers and searches them in parallel. Each provider has its own timeout, so a slow or unavailable site does not prevent results from other sources from appearing.

Results are ranked using text relevance, the provider's ranking, whether the result comes from an API or a scraper, free availability, direct-download support, and source diversity. The response also includes a per-provider report with statuses such as ok, error, timeout, skipped, or link.

Some providers support direct downloads. Poly Haven, ambientCG, Kenney, TextureCan, and free assets from BlenderKit are examples. Other providers return complete metadata and an asset-page link, while Fab, Poliigon, and TurboSquid provide links to their own search pages when bot protection prevents automated searching.

Supported Sources

The provider catalogue includes sources for different kinds of content:

• HDRIs and PBR materials: Poly Haven, ambientCG, HDRMaps, HDRI Hub, and 3DTexel.
• Low-poly and game assets: Kenney, Quaternius, Fab, itch.io, and BlenderKit.
• Textures and scanned materials: CGBookcase, ShareTextures, TextureCan, Textures.com, and 3DTextures.me.
• Models and asset marketplaces: BlenderKit, CGTrader, TurboSquid, Fab, and itch.io.

Licence details vary by listing. For example, Poly Haven, ambientCG, and Kenney offer CC0 content, while marketplace providers may apply listing-specific licences. Always review the returned licence and attribution information before distributing an asset.

Installation and Setup

The project requires Node.js 20 or newer. Clone the repository, install dependencies, and build the application:

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

Start the web UI, HTTP API, and MCP endpoint with:

npm start

The local server runs at http://localhost:8787 by default.

Docker Setup

You can also build and run the server with Docker:

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

Using the Web UI

Open http://localhost:8787 after starting the server. The hosted version is available at 3d.shep.bot.

Use the search page to enter a query, select an asset type, restrict results to free assets, require direct downloads, or select specific providers. Search state is stored in the URL, so a query such as /search?q=sunset&type=hdri&free=true can be bookmarked or shared.

Open a result's detail sheet to review its licence, author, formats, polygon count, tags, available resolutions, and estimated file size. You can then choose a format and resolution, download the asset, copy a curl command, or copy an agent-oriented prompt.

The hosted website also provides documentation, an OpenAPI reference, source information, and self-hosting guidance. Its agent-oriented files include /AGENTS.md, /llms.txt, /llms-full.txt, and /openapi.json.

Searching with the HTTP API

The main search endpoint is GET /v1/search. Provide a query with optional filters such as asset type, free availability, direct-download support, providers, result limit, and offset.

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

A shortened response contains ranked results and provider reports:

{
  "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
    }
  ]
}

Use GET /v1/providers to retrieve the provider catalogue, GET /v1/assets/{provider}:{id} for complete asset details, and GET /v1/assets/{id}/files to inspect the files selected by a format and resolution.

Downloading through the API

For a self-contained file, the download endpoint redirects to the source file. For multi-file assets, it streams a zip containing the asset and its companions:

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

The API also exposes /health, /openapi.json, /v1/catalog, and /v1/stats. The catalog provides provider and asset counts, while the statistics endpoint reports usage and source health.

Using the CLI

The built CLI supports HTTP serving, MCP over standard input and output, and searches from a terminal.

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

Results show a score, asset type, free status, provider identifier, title, and source URL. Provider statuses are printed after the results so you can see which sites responded and which only supplied links.

To run the complete local service from the CLI, use:

3d-asset-server serve

To start an MCP server over standard input and output, use:

3d-asset-server mcp

Using MCP with AI Assistants

MCP lets an AI assistant search for assets, inspect their details, and download permitted files. The available tools are:

• search_assets searches providers using query, type, provider, licence, downloadability, and pagination filters.
• get_asset returns metadata, licence information, available formats and resolutions, and the files a selected download would fetch.
• download_asset saves an asset and its companion files into a configured directory and extracts supported zip packs.
• list_providers describes every provider, its asset types, pricing, licence, and direct-download support.

Claude Code

Configure Claude Code to launch the local MCP process and save files in the current project's asset directory:

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

Claude Desktop, Cursor, and Other Stdio Clients

Add a server entry to the client's MCP configuration:

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

Remote MCP

The hosted server supports Streamable HTTP MCP:

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

For a self-hosted server, point the client to http://<host>:8787/mcp. Remote HTTP downloads are disabled by default because they would write files to the server's disk. In that mode, get_asset returns direct file URLs and a bundle zip URL. Set ASSET_SERVER_HTTP_DOWNLOADS=true only when the server should store the files.

Understanding Downloads

When no format is specified, the server prefers practical game and web formats. Models prefer glb, then gltf, fbx, obj, and blend. HDRIs prefer hdr and then exr. Materials prefer image maps or a zip, textures prefer jpg, png, zip, or exr, and packs are downloaded as extracted zip files.

The default resolution is the closest available option to 2K. Companion files retain their relative paths, allowing a glTF file to find its binary and texture files without manual rearrangement.

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

The downloader only fetches public http and https URLs, refuses private and loopback addresses, enforces a configurable size limit, and rejects unsafe archive paths such as ../. It does not bypass login pages, checkout flows, or hotlink protection.

Configuration

Set environment variables before starting the server to control its network address, providers, downloads, security, and performance.

• PORT and HOST control the HTTP bind address. Their defaults are 8787 and 0.0.0.0.
• ASSET_SERVER_PROVIDERS accepts a comma-separated list such as polyhaven,ambientcg,kenney.
• ASSET_DOWNLOAD_DIR changes the default MCP download folder from ./assets.
• ASSET_SERVER_MAX_DOWNLOAD_BYTES sets the per-download size guard, which defaults to 2 GiB.
• ASSET_SERVER_PROVIDER_TIMEOUT_MS and ASSET_SERVER_HTTP_TIMEOUT_MS adjust provider and HTTP timeouts.
• ASSET_SERVER_CACHE_TTL_MS controls the in-memory HTTP cache duration.
• BLENDERKIT_API_KEY can unlock BlenderKit plan and purchased assets.
• NODE_USE_ENV_PROXY=1 makes Node use the configured HTTPS_PROXY.

Authentication and Rate Limits

Set ASSET_SERVER_API_KEY to protect /v1/* and /mcp. Clients can send the key as a Bearer token, an x-api-key header, or an api_key query parameter. Be careful with query parameters because browser history and server logs may contain them.

Rate limiting is enabled by default at 120 requests per client per 60-second window. Configure ASSET_SERVER_RATE_LIMIT and ASSET_SERVER_RATE_LIMIT_WINDOW, or set the limit to 0 to disable it.

Proxy and Provider Troubleshooting

CGTrader may block cloud and datacenter IP addresses. It often works from a home connection; on a server, configure a proxy and set NODE_USE_ENV_PROXY=1. Scraped providers can also change their HTML. If one breaks, the other sources continue to return results, and npm run test:live can check provider availability.

Advanced Monitoring

Set METRICS_PORT to expose Prometheus metrics on a separate port. The server records bounded-label metrics for searches, provider requests, downloads, asset views, MCP tool calls, HTTP requests, and page views. It also logs structured search events without recording IP addresses, keys, or cookies.

If PROMETHEUS_URL is configured, the statistics endpoint can report aggregate data across replicas. Without it, statistics represent the current process since its last restart.

Recommended Workflow

1. Search broadly with a descriptive query such as sunset, low poly tree, or brick wall.
2. Filter by asset type, free status, direct-download availability, or selected providers.
3. Inspect the licence, attribution requirement, formats, resolutions, and file list.
4. Choose a format and resolution appropriate for your game or website.
5. Download the asset or copy its source link if the provider does not allow direct downloads.
6. Keep any required attribution and licence files with your project.

Conclusion

3d-asset-server turns fragmented asset discovery into a single workflow. Its web UI, HTTP API, CLI, and MCP tools let you search many providers, compare licence and download information, and retrieve ready-to-use models, textures, HDRIs, and packs. Start locally with Node.js or Docker, then configure providers, authentication, download paths, rate limits, and monitoring for a production deployment.