# 3D Asset Server: guide for AI agents

> You are reading the agent guide for https://3d.shep.bot. This service searches 19 3D asset sites at once (Poly Haven, ambientCG, Kenney, BlenderKit, CGTrader, itch.io, Textures.com, HDRMaps and more) and returns 3D models, PBR materials/textures, HDRIs and game asset packs with their licences, plus direct downloads where the source allows. It is free and needs no account or API key.

## When to use this

Reach for 3D Asset Server when the job is one of these:

- **Find an asset for a project**: "get me a low-poly tree", "I need a wooden crate model", "find a sci-fi corridor kit". Search models, packs and sprites across 19 sites in one call instead of browsing each.
- **Get PBR textures or materials**: "mossy rock material", "brick wall 2k textures". Returns map sets (color, normal, roughness, AO, displacement) at 1k–8k.
- **Light a scene with an HDRI**: "sunset HDRI for three.js", "studio environment map". Returns HDR/EXR files at the resolution you ask for.
- **Put files into a codebase**: download glTF/GLB, FBX, Blend, OBJ, textures or HDRIs straight into `./assets` or `./public` for Three.js, Babylon.js, React Three Fiber, Godot, Unity, Unreal, Blender or a website.
- **Check a licence before shipping**: every result carries its licence, whether commercial use is allowed and whether attribution is required.
- **Compare options**: show the user a few candidates (title, source, licence, thumbnail) when the choice is a matter of taste.

## When not to use it

- Generating new 3D models or textures from a prompt (this service finds existing assets; it does not create them).
- Buying paid assets: paid results link to the source site, where the purchase happens.
- Non-3D stock media (photos, video, music libraries); only game-oriented sprites, UI and audio packs are covered.

## Option 1: MCP (best when you can add tools)

MCP endpoint (Streamable HTTP, no auth): `https://3d.shep.bot/mcp`

- Claude Code: `claude mcp add --transport http 3d-assets https://3d.shep.bot/mcp`
- Cursor / Windsurf / VS Code / Codex / Gemini CLI: add an HTTP MCP server with that URL. Per-client snippets: https://3d.shep.bot/docs/mcp

Tools:

- `search_assets(query, types?, free_only?, downloadable_only?, providers?, limit?, offset?)`
- `get_asset(id, format?, resolution?)`: licence, available formats/resolutions, the exact files, and `selection.bundleUrl` to download them
- `list_providers()`

## Option 2: REST API (works with plain HTTP, curl or a fetch tool)

Base URL: `https://3d.shep.bot`. Responses are JSON.

1. Search:
   `GET /v1/search?q=<query>&type=<model|material|texture|hdri|sprite|ui|audio|font|pack>&free=true&limit=10`
   → `results[]` (each has `id`, `title`, `type`, `provider`, `url`, `thumbnailUrl`, `license{name,commercialUse,attributionRequired}`, `price{free}`, `formats`, `resolutions`, `downloadable`) and `providers[]` (per-source status; `status:"link"` entries carry a `searchUrl` for sites that block bots).
2. Inspect one result:
   `GET /v1/assets/{id}` (id like `polyhaven:ArmChair_01`; URL-encode it) → asset + `files[]`.
   `GET /v1/assets/{id}/files?format=gltf&resolution=2k` → the exact files that would be downloaded and `totalBytes`.
3. Download into the project:
   `curl -L -o <name>.zip "https://3d.shep.bot/v1/assets/{id}/download?format=<glb|gltf|fbx|blend|obj|usd|hdr|exr|jpg|png>&resolution=<1k|2k|4k|8k>"`
   A single file redirects (302) to the source CDN (`-L` follows it). Multi-file assets (glTF + .bin + textures, PBR map sets) arrive as one zip; unzip it next to the code that loads it. `409` means no direct download: send the user to the asset's `url`.

Full OpenAPI 3.1 spec: https://3d.shep.bot/openapi.json

## How to do the job well

- Use short, concrete queries: "wooden crate", "brick wall", "sunset", "low poly tree". Add `type` to cut noise; `material` and `texture` match each other.
- Prefer `free=true`, and prefer CC0 sources (Poly Haven, ambientCG, Kenney, TextureCan, 3DTextures.me) for commercial work.
- Prefer `downloadable: true` results when the user wants files in their project.
- Formats: web/three.js → `glb` or `gltf`; Blender → `blend`; Unity/Unreal → `fbx`; environment lighting → `hdr` or `exr` HDRI; PBR textures → `jpg`/`png` maps at `2k` unless asked otherwise.
- Before downloading big files, check `/files` for `totalBytes`; 8k textures and 16k HDRIs can be hundreds of MB.
- Always tell the user each asset's licence, and when `attributionRequired` is true, give the exact credit line (title, author, source URL, licence).
- Show a few options (title, source, licence, thumbnail URL) when the choice is subjective; download directly when the request is specific.
- To let the user see an asset (or share it), link `https://3d.shep.bot/search?asset=<id>`: it opens the asset with its preview, licence and downloads, and unfurls in chat apps with a card showing its thumbnail.
- If a search comes back thin, try a simpler synonym, drop filters, or pass along the `searchUrl` links of `link` sources (Fab, Poliigon, TurboSquid).

## Example

User: "Add a CC0 sunset HDRI to my three.js scene."

```bash
curl -s "https://3d.shep.bot/v1/search?q=sunset&type=hdri&free=true&downloadable=true&limit=5"
# pick e.g. polyhaven:venice_sunset, then:
mkdir -p public/env
curl -L -o public/env/venice_sunset_2k.hdr "https://3d.shep.bot/v1/assets/polyhaven%3Avenice_sunset/download?format=hdr&resolution=2k"
```

Then load it with `RGBELoader` and set `scene.environment`, and tell the user: "Venice Sunset by Greg Zaal, Poly Haven, CC0 (no attribution required)."

## More

- Human docs: https://3d.shep.bot/docs
- Coding agent setup: https://3d.shep.bot/docs/mcp
- REST guide: https://3d.shep.bot/docs/api
- Sources and licences: https://3d.shep.bot/docs/sources
- How many assets each source holds (counted daily): https://3d.shep.bot/stats.md, JSON at https://3d.shep.bot/v1/catalog
- Everything as one text file: https://3d.shep.bot/llms-full.txt

---

# 3D Asset Server quick start

**3D Asset Server** searches 19 3D asset sites at once and downloads what you pick, ready to drop into a game or a website. Results cover 3D models, PBR materials, textures, HDRIs and game asset packs, and every result shows its licence.

The public server at **https://3d.shep.bot** is free and needs no account or API key.

## Pick how you want to use it

| You want to… | Use | Start here |
| --- | --- | --- |
| Browse and download assets yourself | The web search | [/search](https://3d.shep.bot/search) |
| Let Claude Code, Cursor, Copilot or another agent fetch assets | The MCP server at `https://3d.shep.bot/mcp` | [Coding agents & MCP](https://3d.shep.bot/docs/mcp) |
| Call it from a script, build tool or backend | The REST API | [REST API guide](https://3d.shep.bot/docs/api) |
| Explore every endpoint and try requests | The interactive reference | [API reference](https://3d.shep.bot/docs/api/reference) |

## Connect your coding agent (30 seconds)

For **Claude Code**, run this once:

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

Then ask for what you need:

```text
Find a CC0 sunset HDRI and a mossy rock PBR material (2k) and put them in ./assets.
Tell me the licence of each.
```

Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI and the Claude apps take the same URL. See [Coding agents & MCP](https://3d.shep.bot/docs/mcp) for each one.

## Or call the API

```bash
# Search every source for free low-poly tree models
curl "https://3d.shep.bot/v1/search?q=low+poly+tree&type=model&free=true&limit=5"

# Details and files for one result
curl "https://3d.shep.bot/v1/assets/polyhaven:ArmChair_01"

# Download it as glTF (multi-file assets arrive as one zip)
curl -L -o armchair.zip "https://3d.shep.bot/v1/assets/polyhaven:ArmChair_01/download?format=gltf&resolution=2k"
```

## What a search returns

Every search returns two lists:

- **`results`**: assets merged from all sources, ranked by text match, the source's own ranking, whether they're free and whether files can be downloaded directly. Each one has an `id` like `polyhaven:ArmChair_01`, a `license`, a `price`, known `formats` and `resolutions`, and `downloadable`.
- **`providers`**: one status line per source (`ok`, `error`, `timeout`, `skipped` or `link`). Sites that block bots (Fab, Poliigon, TurboSquid) come back as `link` with a `searchUrl` that runs the same search on their site.

A slow or broken source never fails the search.

## Licences

Assets keep the licence of the site they come from. Poly Haven, ambientCG, Kenney, TextureCan and 3DTextures.me publish under **CC0** (public domain: commercial use, no credit needed). Others are royalty-free, need attribution, or are paid. Check `license.attributionRequired` before you ship. See [Sources & licences](https://3d.shep.bot/docs/sources).

## For AI agents reading this

Machine-readable entry points:

- [/AGENTS.md](https://3d.shep.bot/AGENTS.md): how to use this service as an agent
- [/llms.txt](https://3d.shep.bot/llms.txt) and [/llms-full.txt](https://3d.shep.bot/llms-full.txt): site index and full docs as plain text
- [/openapi.json](https://3d.shep.bot/openapi.json): OpenAPI 3.1 description of the REST API

---
Source: https://3d.shep.bot/docs

---

# 3D Asset Server MCP server for coding agents

3D Asset Server is a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect it once and your coding agent can search 19 asset sites, check licences and pull models, textures and HDRIs into your project while it writes the code that uses them.

**MCP endpoint:** `https://3d.shep.bot/mcp` (Streamable HTTP, no authentication).

## Claude Code

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

Add `--scope user` to make it available in every project, or `--scope project` to share it with your team through `.mcp.json`. Check it with `claude mcp list`, or `/mcp` inside a session.

## Cursor

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=3d-assets&config=eyJ1cmwiOiJodHRwczovLzNkLnNoZXAuYm90L21jcCJ9) (opens Cursor), or add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "3d-assets": { "url": "https://3d.shep.bot/mcp" }
  }
}
```

## VS Code (GitHub Copilot)

Add to `.vscode/mcp.json`, then use Copilot Chat in **Agent** mode:

```json
{
  "servers": {
    "3d-assets": { "type": "http", "url": "https://3d.shep.bot/mcp" }
  }
}
```

Or from a terminal: `code --add-mcp '{"name":"3d-assets","type":"http","url":"https://3d.shep.bot/mcp"}'`

## Claude desktop app and claude.ai

Open **Settings → Connectors → Add custom connector**, name it *3D Asset Server* and paste `https://3d.shep.bot/mcp`.

## Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "3d-assets": { "serverUrl": "https://3d.shep.bot/mcp" }
  }
}
```

## OpenAI Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.3d-assets]
url = "https://3d.shep.bot/mcp"
```

## Gemini CLI

```bash
gemini mcp add --transport http 3d-assets https://3d.shep.bot/mcp
```

## Any other client

Clients that only support stdio servers can bridge to the HTTP endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "3d-assets": { "command": "npx", "args": ["-y", "mcp-remote", "https://3d.shep.bot/mcp"] }
  }
}
```

## Tools your agent gets

| Tool | What it does |
| --- | --- |
| `search_assets` | Search every source. Arguments: `query`, `types` (model, material, texture, hdri, sprite, ui, audio, font, pack), `free_only`, `downloadable_only`, `providers`, `limit`, `offset`. |
| `get_asset` | Details for one `id` from a search: licence, formats, resolutions, and the exact files for a `format` and `resolution`, plus a `bundleUrl` that downloads them as one file or zip. |
| `list_providers` | Every source with what it is best for, pricing, licence and whether it supports direct downloads. |

The remote server never writes to its own disk, so agents download through the `bundleUrl` that `get_asset` returns:

```bash
curl -L -o assets/armchair.zip "https://3d.shep.bot/v1/assets/polyhaven%3AArmChair_01/download?format=gltf&resolution=2k"
unzip -o assets/armchair.zip -d assets/
```

Coding agents with a shell do this on their own.

## Prompts that work well

```text
Find a CC0 sunset HDRI (4k EXR) and add it to ./public/env. Wire it into the Three.js scene as the environment map.
```

```text
I need a low-poly tree pack for a browser game. Search free models, show me 5 options with licences, then download the one I pick as glTF into ./assets/trees.
```

```text
Get a 2k mossy rock PBR material with color, normal, roughness and AO maps and make a MeshStandardMaterial from it.
```

Tips for agents and the people prompting them:

- Use short, concrete queries: "wooden crate", "brick wall", "night city hdri".
- Filter by type. `material` and `texture` match each other.
- Prefer CC0 sources for commercial projects, and always report the licence and any attribution requirement.
- Results with `downloadable: false` must be fetched from their `url` on the source site.

## Local mode: downloads straight to disk

For a `download_asset` tool that writes files (glTF with `.bin` and textures, extracted zips) directly into your project, run the server locally over stdio with Docker:

```bash
claude mcp add 3d-assets-local -- docker run -i --rm \
  --user "$(id -u):$(id -g)" -v "$PWD/assets:/app/assets" \
  ghcr.io/arielshad/3d-asset-server node dist/cli.js mcp
```

Files land in `./assets/<provider>-<id>/`. Add `-e BLENDERKIT_API_KEY=...` to unlock BlenderKit plan assets.

## Agents without MCP

Any agent that can fetch URLs can use the REST API directly. Point it at [/AGENTS.md](https://3d.shep.bot/AGENTS.md); it has the whole workflow in a few lines. In Claude Code you can also install the ready-made skill:

```bash
mkdir -p ~/.claude/skills/3d-assets
curl -fsSL https://3d.shep.bot/skill/SKILL.md -o ~/.claude/skills/3d-assets/SKILL.md
```

---
Source: https://3d.shep.bot/docs/mcp

---

# 3D Asset Server REST API guide

A small JSON API over HTTPS. No key is needed on `https://3d.shep.bot`. Every endpoint is described in the [OpenAPI 3.1 spec](https://3d.shep.bot/openapi.json), which you can explore and try in the [interactive reference](https://3d.shep.bot/docs/api/reference).

**Base URL:** `https://3d.shep.bot`

## The flow

1. `GET /v1/search`: find candidates across every source.
2. `GET /v1/assets/{id}`: read the licence, formats and files of one result.
3. `GET /v1/assets/{id}/download`: get the file, or a zip of the file and its companions.

## Search

```bash
curl "https://3d.shep.bot/v1/search?q=wooden+chair&type=model&free=true&limit=10"
```

| Parameter | Description |
| --- | --- |
| `q` | Free-text query. Short and concrete works best. |
| `type` | Comma-separated: `model`, `material`, `texture`, `hdri`, `sprite`, `ui`, `audio`, `font`, `pack`, `other`. |
| `free` | `true` for free assets only. |
| `downloadable` | `true` for assets this server can download directly. |
| `providers` | Comma-separated source ids from `/v1/providers`, e.g. `polyhaven,ambientcg`. |
| `limit` | Max results, 1–100 (default 24). |
| `offset` | Per-source offset for the next page (e.g. `24`). |

The response:

```json
{
  "query": "wooden chair",
  "results": [
    {
      "id": "polyhaven:WoodenChair_01",
      "title": "Wooden Chair 01",
      "type": "model",
      "provider": "polyhaven",
      "url": "https://polyhaven.com/a/WoodenChair_01",
      "thumbnailUrl": "https://cdn.polyhaven.com/...",
      "license": { "name": "CC0", "commercialUse": true, "attributionRequired": false },
      "price": { "free": true },
      "formats": ["gltf", "blend", "fbx", "usd"],
      "resolutions": ["1k", "2k", "4k"],
      "downloadable": true
    }
  ],
  "providers": [
    { "provider": "polyhaven", "name": "Poly Haven", "status": "ok", "count": 6, "tookMs": 412 },
    { "provider": "fab", "name": "Fab", "status": "link", "count": 0, "searchUrl": "https://www.fab.com/search?q=wooden+chair" }
  ]
}
```

## Asset details

```bash
curl "https://3d.shep.bot/v1/assets/polyhaven:WoodenChair_01"
```

Returns the asset plus `files[]`. Each file has `url`, `filename`, `format`, `resolution`, `sizeBytes`, and `includes[]` for companions that must sit next to it (a `.gltf`'s `.bin` and textures).

## Choose files

```bash
curl "https://3d.shep.bot/v1/assets/polyhaven:WoodenChair_01/files?format=gltf&resolution=2k"
```

Smart selection for a `format` (`glb`, `gltf`, `fbx`, `blend`, `obj`, `usd`, `hdr`, `exr`, `jpg`, `png`, `zip`) and a `resolution` (`1k`, `2k`, `4k`, `8k`; the closest available is used). For texture sets, `maps=diff,nor_gl,rough,ao` picks map types. `all=true` returns everything.

## Download

```bash
curl -L -o chair.zip "https://3d.shep.bot/v1/assets/polyhaven:WoodenChair_01/download?format=gltf&resolution=2k"
```

A single self-contained file answers with a `302` redirect to the source CDN (so use `-L`). Multi-file selections stream as one zip with the right folder layout. Assets without direct downloads answer `409` with the asset's `url`.

## List sources

```bash
curl "https://3d.shep.bot/v1/providers"
```

## Usage statistics and source health

```bash
curl "https://3d.shep.bot/v1/stats"
```

Aggregate usage (searches by surface, downloads, MCP tool calls, top clients and asset types) for the last 24 hours and 7 days, plus each source's success rate and p50/p95 latency. Check `providers[]` to see which sources are slow or failing right now. The same data is on the [usage statistics](https://3d.shep.bot/stats) page.

## Examples

### JavaScript / TypeScript

```ts
const base = "https://3d.shep.bot";
const res = await fetch(`${base}/v1/search?` + new URLSearchParams({ q: "sunset", type: "hdri", free: "true" }));
const { results } = await res.json();
const hdri = results.find((a) => a.downloadable);
console.log(hdri.title, hdri.license.name);
const fileUrl = `${base}/v1/assets/${encodeURIComponent(hdri.id)}/download?format=exr&resolution=4k`;
```

### Python

```python
import requests

base = "https://3d.shep.bot"
r = requests.get(f"{base}/v1/search", params={"q": "brick wall", "type": "material", "free": "true"})
asset = next(a for a in r.json()["results"] if a["downloadable"])

with requests.get(f"{base}/v1/assets/{asset['id']}/download", params={"resolution": "2k"}, stream=True) as dl:
    dl.raise_for_status()
    with open("brick.zip", "wb") as f:
        for chunk in dl.iter_content(1 << 16):
            f.write(chunk)
```

## Errors

Errors are JSON: `{ "error": "message" }`.

| Status | Meaning |
| --- | --- |
| `400` | Bad parameter or unknown source id. |
| `401` | API key required (self-hosted servers with `ASSET_SERVER_API_KEY` only). |
| `404` | Unknown asset, or no file matches the format/resolution. |
| `409` | The source has no direct downloads; use the returned `url`. |
| `429` | Rate limit exceeded; wait `Retry-After` seconds. |
| `502` | The source site failed. |

## Authentication (self-hosted)

The public server is open. If you run your own with `ASSET_SERVER_API_KEY`, send the key as `Authorization: Bearer <key>` or `x-api-key: <key>` (or `?api_key=` for plain download links).

## Rate limits and versioning

The public server allows 120 requests per minute per client. Every response carries `RateLimit-Policy` and `RateLimit` headers (plus `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`); going over returns `429` with `Retry-After`. The API is versioned in the path (`/v1`), only grows additively within a version, and announces deprecations with `Deprecation` and `Sunset` headers at least 90 days ahead. Details: [Versioning, deprecation & rate limits](https://3d.shep.bot/docs/api/versioning).

## Fair use

Please cache results on your side for repeated queries, keep requests to a human pace, and respect each asset's licence. The server already caches source responses for a few minutes and deduplicates identical in-flight requests.

---
Source: https://3d.shep.bot/docs/api

---

# Versioning, deprecation & rate limits

The rules below let agents and integrations build on the 3D Asset Server API without surprises.

## Versioning

- The major version is part of the path: every REST endpoint lives under **`/v1`**.
- Within `/v1`, changes are **additive only**: new endpoints, new optional parameters, new fields in responses. Clients must ignore fields they don't know.
- **Breaking changes** (removing or renaming a field or endpoint, changing a type or a default) only ship under a new major version (`/v2`). The previous version keeps working during its deprecation period.
- The MCP tools follow the same rule: tool names and existing arguments stay stable; new optional arguments may appear.
- The OpenAPI document at [/openapi.json](https://3d.shep.bot/openapi.json) always describes the current version. Its `info.version` follows semantic versioning.

## Deprecation and sunset

When an endpoint, parameter or whole API version is going away:

1. It is marked `deprecated: true` in the OpenAPI document and listed in the changelog on GitHub.
2. Its responses carry a **`Deprecation`** header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) with the date it was deprecated, a **`Sunset`** header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the date it stops working, and a `Link: <…>; rel="deprecation"` header pointing at migration notes.
3. The sunset date is **at least 90 days** after the deprecation is announced.
4. After the sunset date the endpoint answers `410 Gone` with a JSON body naming its replacement.

Example of a deprecated response:

```http
HTTP/1.1 200 OK
Deprecation: @1767225600
Sunset: Wed, 01 Apr 2026 00:00:00 GMT
Link: <https://3d.shep.bot/docs/api/versioning>; rel="deprecation"
```

Nothing in `/v1` is deprecated today.

## Rate limits

The public server allows **120 requests per minute per client** across `/v1/*` and `/mcp`. Every response tells you where you stand, using the IETF RateLimit header fields plus their widely used single-value forms:

| Header | Example | Meaning |
| --- | --- | --- |
| `RateLimit-Policy` | `"default";q=120;w=60` | Quota: 120 requests (`q`) per 60-second window (`w`). |
| `RateLimit` | `"default";r=117;t=42` | 117 requests remaining (`r`), window resets in 42 seconds (`t`). |
| `RateLimit-Limit` | `120` | Requests per window. |
| `RateLimit-Remaining` | `117` | Requests left in this window. |
| `RateLimit-Reset` | `42` | Seconds until the window resets. |

Going over the limit returns **`429 Too Many Requests`** with a **`Retry-After`** header (seconds) and a JSON body:

```json
{ "error": "Rate limit exceeded: 120 requests per 60s. Retry after 12s.", "retryAfter": 12 }
```

How to behave:

- Read `RateLimit-Remaining` (or `r=` in `RateLimit`) and slow down before it reaches zero.
- On `429`, wait `Retry-After` seconds, then retry once. Don't retry in a tight loop.
- Cache search results you reuse; a search fans out to 19 sites, so repeating it costs everyone.

All rate-limit headers are exposed to browsers through CORS. Self-hosted servers set their own limit with `ASSET_SERVER_RATE_LIMIT` and `ASSET_SERVER_RATE_LIMIT_WINDOW` (see [Self-hosting](https://3d.shep.bot/docs/self-hosting)).

---
Source: https://3d.shep.bot/docs/api/versioning

---

# Sources & licences

3D Asset Server searches 19 sites. Use the `id` with `providers=` to restrict a search.

| Source | id | Best for | Types | Pricing | Licence | Direct download |
| --- | --- | --- | --- | --- | --- | --- |
| [Poly Haven](https://polyhaven.com) | `polyhaven` | Free CC0 HDRIs, PBR textures and photoscanned 3D models with a public API. | hdri, material, texture, model | free | CC0 | yes |
| [ambientCG](https://ambientcg.com) | `ambientcg` | Free CC0 PBR materials, HDRIs, decals and atlases (1K-16K) with a public JSON API and direct downloads. | material, texture, hdri, model | free | CC0 | yes |
| [cgbookcase](https://www.cgbookcase.com) | `cgbookcase` | Free CC0 PBR textures up to 8K (scanned, procedural and approximated). | material, texture | free | CC0 | no |
| [ShareTextures](https://www.sharetextures.com) | `sharetextures` | Free CC0-style PBR textures, scanned 3D models and atlases (search by tag; download on the site). | material, texture, model, pack | free | CC0 (ShareTextures custom terms) | no |
| [BlenderKit](https://www.blendkit.com) | `blenderkit` | Blender-native models, materials, HDRIs, scenes and brushes (free + Full Plan) with a public search API; free assets download as .blend/.glb. | model, material, hdri, other | freemium | per asset | yes |
| [Fab](https://www.fab.com) | `fab` | Epic's marketplace (formerly Unreal Marketplace, Sketchfab Store, Quixel): game-ready models, environments, characters, materials. | model, material, texture, pack, audio | freemium | per asset | no |
| [Kenney](https://kenney.nl/assets) | `kenney` | Hundreds of CC0 game asset packs (low-poly 3D kits, 2D sprites, UI, audio, fonts) by Kenney. | model, sprite, ui, audio, font, texture, other | free | CC0 | yes |
| [Poliigon](https://www.poliigon.com) | `poliigon` | Premium photoreal PBR materials, HDRIs and models (subscription, with a free selection). | material, texture, hdri, model | freemium | per asset | no |
| [Quaternius](https://quaternius.com) | `quaternius` | Free low-poly 3D model packs and animated, rigged characters by Quaternius (CC0 or the similar QAL). | model | free | per asset | no |
| [Polyfork](https://polyfork.dev) | `polyfork` | Low-poly, game- and web-ready 3D models (props, buildings, vehicles, characters, themed kits) with a public API; free assets download as GLB. | model | freemium | Royalty Free | yes |
| [3DTextures.me](https://3dtextures.me) | `threedtextures` | Free CC0 seamless PBR materials, realistic and stylized (WordPress blog; downloads via Google Drive). | material | free | CC0 | no |
| [3DTexel](https://3dtexel.com) | `threedtexel` | Free handmade CC0 PBR materials, HDRIs, 3D assets, decals and atlases (search via its public API; download with a free account). | material, texture, hdri, model, other | free | per asset | no |
| [TextureCan](https://www.texturecan.com) | `texturecan` | Free CC0 PBR textures (4K, many with SBSAR sources) and a few CC0 3D models, direct zip downloads. | material, model | free | CC0 | yes |
| [Textures.com](https://www.textures.com) | `texturescom` | Huge photo-texture library: PBR materials, scanned 3D foliage/objects, decals, ornaments and HDR skies (credit-based, daily free credits). | texture, material, model, hdri | freemium | per asset | no |
| [HDRMAPS](https://hdrmaps.com) | `hdrmaps` | High-resolution HDRIs and sky domes (paid shop) plus a set of free HDRIs with direct EXR downloads. | hdri, model, pack, other | freemium | Royalty Free | yes |
| [HDRI Hub](https://www.hdri-hub.com) | `hdrihub` | Commercial high-resolution HDRIs, backplates and 3D people for archviz, plus a few free samples. | hdri, model, texture, other | freemium | Royalty Free | no |
| [CGTrader](https://www.cgtrader.com) | `cgtrader` | Large marketplace of free and paid 3D models (game, archviz, 3D print); downloads need a CGTrader account. | model | freemium | per asset | no |
| [TurboSquid](https://www.turbosquid.com) | `turbosquid` | Large marketplace of free and paid 3D models. | model | freemium | per asset | no |
| [itch.io](https://itch.io/game-assets) | `itchio` | Indie game asset packs (3D, 2D sprites, UI, audio, fonts), free and paid, from itch.io creators. | model, sprite, texture, material, ui, audio, font, pack, other | freemium | per asset | no |

CC0 = public domain (commercial use, no credit needed). Sources marked "per asset" set licences per listing; check each result's `license`.

---

# 3D Asset Server CLI

The `3d-asset-server` command searches every source from a terminal, runs the MCP server over stdio for desktop agents, and starts the HTTP server. It is the same code that runs https://3d.shep.bot.

## Commands

```text
3d-asset-server search <query> [--type model,hdri] [--free] [--providers polyhaven,kenney] [--limit N]
3d-asset-server mcp      # MCP server over stdio, with download_asset writing to ./assets
3d-asset-server serve    # HTTP API + website + MCP at /mcp on port 8787
```

`search` prints ranked results (score, type, price, asset id, title and URL) followed by one status line per source:

```text
0.92  model    free   polyhaven:ArmChair_01
      Arm Chair 01 — https://polyhaven.com/a/ArmChair_01

Sources:
  polyhaven        ok       12
  fab              link     0  https://www.fab.com/search?q=chair
```

Pass the asset id to the REST API (`/v1/assets/{id}/download`) or the MCP `get_asset` tool to fetch files.

## Run it with Docker (no install)

```bash
docker run --rm ghcr.io/arielshad/3d-asset-server node dist/cli.js search "low poly tree" --type model --free
```

As a local MCP server that writes downloads into your project:

```bash
docker run -i --rm --user "$(id -u):$(id -g)" -v "$PWD/assets:/app/assets" \
  ghcr.io/arielshad/3d-asset-server node dist/cli.js mcp
```

## Run it from source

```bash
git clone https://github.com/arielshad/3d-asset-server
cd 3d-asset-server && npm ci && npm run build:server
node dist/cli.js search "sunset" --type hdri --free
```

## Environment

| Variable | Purpose |
| --- | --- |
| `ASSET_SERVER_PROVIDERS` | Comma list to search only some sources. |
| `ASSET_DOWNLOAD_DIR` | Where `mcp` downloads go (default `./assets`). |
| `BLENDERKIT_API_KEY` | Unlocks BlenderKit plan and purchased assets. |
| `NODE_USE_ENV_PROXY` | Set to `1` so the CLI honours `HTTPS_PROXY`. |

See [Self-hosting](https://3d.shep.bot/docs/self-hosting) for every server setting.

---
Source: https://3d.shep.bot/docs/cli

---

# Self-hosting 3D Asset Server

3D Asset Server is open source (Apache-2.0). Run your own copy to put it behind your own key, enable more sources, or let the MCP server write files to a shared disk.

## Docker

```bash
docker run -p 8787:8787 ghcr.io/arielshad/3d-asset-server
```

Open http://localhost:8787 for the website, `/v1/*` for the API and `/mcp` for MCP.

## Node.js

```bash
git clone https://github.com/arielshad/3d-asset-server
cd 3d-asset-server
npm ci && npm run build
npm start
```

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `PORT` / `HOST` | `8787` / `0.0.0.0` | HTTP bind address. |
| `ASSET_SERVER_API_KEY` | none | Require `Authorization: Bearer <key>`, `x-api-key` or `?api_key=` on `/v1/*` and `/mcp`. |
| `ASSET_SERVER_PUBLIC_URL` | request origin | Base URL used in links handed to MCP clients. Set it behind a TLS proxy. |
| `ASSET_SERVER_PROVIDERS` | all | Comma list to enable only some sources. |
| `ASSET_SERVER_HTTP_DOWNLOADS` | `false` | Expose `download_asset` on the HTTP MCP endpoint (writes to the server's disk). |
| `ASSET_DOWNLOAD_DIR` | `./assets` | Where MCP downloads go. |
| `ASSET_SERVER_PROVIDER_TIMEOUT_MS` | `12000` | Per-source search timeout. |
| `BLENDERKIT_API_KEY` | none | Unlocks plan and purchased BlenderKit assets. |
| `ASSET_SERVER_RATE_LIMIT` | `120` | Requests per client per window on `/v1/*` and `/mcp`, with RateLimit headers and `429` + `Retry-After` beyond it. `0` turns it off. |
| `ASSET_SERVER_RATE_LIMIT_WINDOW` | `60` | Rate-limit window in seconds. |
| `METRICS_PORT` | off | Serve Prometheus metrics on this port at `/metrics`, and log one JSON line per search, download and tool call. |
| `PROMETHEUS_URL` | off | Prometheus that scrapes `METRICS_PORT`. `/v1/stats` and the `/stats` page then show the last 24 hours and 7 days; without it they count since the server started. |

## Analytics

With `METRICS_PORT` set, the server exports Prometheus metrics with bounded labels only (surface, client family, source, status, tool):

- `asset_server_searches_total`, `asset_server_search_duration_seconds`, `asset_server_search_results`
- `asset_server_provider_requests_total` and `asset_server_provider_duration_seconds` for each source's health and latency
- `asset_server_downloads_total`, `asset_server_asset_views_total`
- `asset_server_mcp_tool_calls_total` by tool and client family (Claude Code, Cursor, VS Code, …)
- `asset_server_http_requests_total`, `asset_server_page_views_total`

The [/stats](https://3d.shep.bot/stats) page and `GET /v1/stats` read these counters back: from Prometheus when `PROMETHEUS_URL` is set, otherwise from this process since it started.

Each search also logs a JSON line (`{"event":"search","query":…,"results":…}`) for top-query and zero-result analysis in Loki or any log store. Nothing personal is recorded: no IPs, keys or cookies.

## Stdio MCP

```bash
node dist/cli.js mcp
```

Runs the MCP server over stdio with the `download_asset` tool enabled, for desktop clients that launch a local process.

---
Source: https://3d.shep.bot/docs/self-hosting

---

# About 3D Asset Server

**3D Asset Server** (https://3d.shep.bot) is a free search engine and API for 3D assets. One query searches 19 asset sites at once, including Poly Haven, ambientCG, Kenney, BlenderKit, CGTrader and itch.io, and returns 3D models, PBR materials and textures, HDRIs and game asset packs with the licence of every result. Where a source allows it, the server also downloads the files: glTF/GLB, FBX or Blend models with their textures, PBR texture maps at 1k–8k, and HDR/EXR environment maps.

It exists because finding a usable asset usually means opening a dozen tabs, comparing licences by hand, and unpacking archives in different layouts. 3D Asset Server does that comparison once and hands back files that are ready to drop into a game, a website or a Blender scene.

## Who it is for

- **Game and web developers** who need a model, a material or an environment map now, with a licence they can ship.
- **AI coding agents** (Claude Code, Cursor, GitHub Copilot, Windsurf, Codex and others) that build scenes and need to find, vet and fetch assets on their own. The service is an [MCP server](https://3d.shep.bot/docs/mcp) and has an [agent guide](https://3d.shep.bot/AGENTS.md).
- **Tools and pipelines** that call the [REST API](https://3d.shep.bot/docs/api) from scripts or build steps.

## Who runs it

3D Asset Server is open source under the Apache-2.0 licence and developed in the open at [github.com/arielshad/3d-asset-server](https://github.com/arielshad/3d-asset-server). The public instance runs on Shep's infrastructure ([shep.bot](https://shep.bot)). Anyone can [self-host](https://3d.shep.bot/docs/self-hosting) their own copy.

## How it treats sources and licences

- **Assets belong to their creators.** The service never re-hosts assets. Downloads either redirect to the source's own CDN or stream files from it, unchanged.
- **Licences come first.** Every result shows its licence, whether commercial use is allowed and whether attribution is required, as published by the source. When a licence is unclear, the result links to the original page.
- **Polite access.** The server identifies itself with a descriptive User-Agent, caches responses for several minutes, deduplicates identical requests and gives every source its own timeout. Sites that ask not to be crawled (Fab, Poliigon, TurboSquid) are never scraped; they only get a deep link to their own search.

See [Sources & licences](https://3d.shep.bot/docs/sources) for the full list, [Privacy](https://3d.shep.bot/privacy) for what the service records, and [Contact](https://3d.shep.bot/contact) to reach the maintainers.

---
Source: https://3d.shep.bot/about

---

# 3D assets in numbers

Counted 2026-10-06 (daily). Machine-readable: `GET https://3d.shep.bot/v1/catalog` (same as https://3d.shep.bot/catalog.json; daily history at https://3d.shep.bot/catalog-history.json). "+" marks lower bounds.

## Totals

- Asset listings: 2,953,975+ from 15 counted sources (a listing is one asset, or one pack on Kenney, Quaternius and itch.io)
- Free: 243,882+
- CC0 / public domain: 8,221
- Free with direct download through this server: 34,997+
- Released in the last 30 days (sources that date their listings): 30

## By asset type

- 3D models: 2,739,142+
- Asset packs: 118,697
- Textures: 57,115
- PBR materials: 17,561+
- HDRIs: 12,890+
- Other: 8,209+
- Sprites: 126
- UI kits: 18
- Audio: 10
- Fonts: 1

## By source

| Source | Listings | Free | Mostly | New (30 days) |
| --- | --- | --- | --- | --- |
| [CGTrader](https://www.cgtrader.com) | 2,719,278 | 149,177 | 3D models 2,719,278 | – |
| [itch.io](https://itch.io/game-assets) | 118,644 packs | 55,324 | Asset packs 118,644 | – |
| [Textures.com](https://www.textures.com) | 59,171 | – | Textures 56,820, 3D models 1,756, HDRIs 595 | – |
| [BlenderKit](https://www.blendkit.com) | 43,044+ | 27,807 | 3D models 14,927, PBR materials 10,000, HDRIs 10,000 | – |
| [ambientCG](https://ambientcg.com) | 2,898 | 2,898 | PBR materials 2,222, HDRIs 431, Textures 206 | 13 |
| [Poly Haven](https://polyhaven.com) | 2,383 | 2,383 | HDRIs 997, PBR materials 865, 3D models 521 | 13 |
| [ShareTextures](https://www.sharetextures.com) | 2,247 | 2,220 | PBR materials 1,771, 3D models 386, Textures 63 | – |
| [Polyfork](https://polyfork.dev) | 2,011 | 821 | 3D models 2,011 | – |
| [3DTextures.me](https://3dtextures.me) | 1,500 | 1,498 | PBR materials 1,500 | 4 |
| [HDRMAPS](https://hdrmaps.com) | 875 | 214 | HDRIs 623, Asset packs 26, 3D models 17 | – |
| [TextureCan](https://www.texturecan.com) | 658 | 658 | PBR materials 650, 3D models 8 | – |
| [cgbookcase](https://www.cgbookcase.com) | 566 | 566 | PBR materials 553, Textures 13 | 0 |
| [HDRI Hub](https://www.hdri-hub.com) | 401 | 17 | HDRIs 244, Other 88, 3D models 66 | – |
| [Kenney](https://kenney.nl/assets) | 216 packs | 216 | Sprites 126, 3D models 50, UI kits 18 | – |
| [Quaternius](https://quaternius.com) | 83 packs | 83 | 3D models 83 | – |

## Most downloaded

- Most downloaded this month on ambientCG: [Wood 096](https://ambientcg.com/a/Wood096) (2,254 downloads)
- Most downloaded HDRI on Poly Haven: [Kloofendal 48d Partly Cloudy (Pure Sky)](https://polyhaven.com/a/kloofendal_48d_partly_cloudy_puresky) (874,859 downloads)
- Most downloaded texture on Poly Haven: [Plywood](https://polyhaven.com/a/plywood) (731,712 downloads)
- Most downloaded model on Poly Haven: [Grass Medium 01](https://polyhaven.com/a/grass_medium_01) (241,756 downloads)
- Most downloaded on ShareTextures: [Velvet 2](https://www.sharetextures.com/textures/fabric/velvet_2) (23,509 downloads)

## Live usage

Searches, downloads, MCP tool calls and per-source health change every minute: read them from `GET https://3d.shep.bot/v1/stats` (schema `Stats` in https://3d.shep.bot/openapi.json). Counts are anonymous totals: no search terms, IP addresses or user agents.

## Recently added sources

- [3DTexel](https://3dtexel.com) (`threedtexel`), added 2026-10-06
- [Polyfork](https://polyfork.dev) (`polyfork`), added 2026-10-06
- [3DTextures.me](https://3dtextures.me) (`threedtextures`), added 2026-10-04
- [ambientCG](https://ambientcg.com) (`ambientcg`), added 2026-10-04
- [BlenderKit](https://www.blendkit.com) (`blenderkit`), added 2026-10-04
- [cgbookcase](https://www.cgbookcase.com) (`cgbookcase`), added 2026-10-04

All sources: https://3d.shep.bot/docs/sources.md

---

# Contact

3D Asset Server is maintained in the open. The fastest way to reach the maintainers is GitHub, where every conversation stays public and searchable for the next person with the same question.

## Support and bug reports

Open an issue at [github.com/arielshad/3d-asset-server/issues](https://github.com/arielshad/3d-asset-server/issues). Helpful details: the search query or asset id (for example `polyhaven:ArmChair_01`), the URL or MCP tool you called, what you expected and what happened. For API problems, include the response status and body.

## Security issues

Please do not open a public issue for a vulnerability. Report it privately through GitHub's security advisories at [github.com/arielshad/3d-asset-server/security/advisories/new](https://github.com/arielshad/3d-asset-server/security/advisories/new). You will get an acknowledgement, and fixes are released as soon as they are ready.

## Asset sources and licences

If you run one of the sites the service searches and want your source changed, rate-limited further or removed, or if a licence is shown incorrectly, open an issue with the asset id or source name. Requests from site owners are handled first. Assets themselves are never hosted here, so questions about using a specific asset go to its creator on the source site.

## Integrations and partnerships

Building something on top of the API or the MCP server, or want your asset library added as a source? Open an issue describing the integration. The [provider guide](https://github.com/arielshad/3d-asset-server/blob/main/docs/PROVIDERS_GUIDE.md) explains how new sources are added.

## Machine-readable entry points

- Agent guide: [/AGENTS.md](https://3d.shep.bot/AGENTS.md)
- Site index for LLMs: [/llms.txt](https://3d.shep.bot/llms.txt)
- API description: [/openapi.json](https://3d.shep.bot/openapi.json)

---
Source: https://3d.shep.bot/contact

---

# Privacy

3D Asset Server has no accounts, no sign-up, no advertising and no tracking cookies. This page explains exactly what the public service at https://3d.shep.bot records and why.

## What the service records

- **Search events.** For each search the server logs the search text, the asset-type filters, the number of results, which interface was used (website, API or MCP) and a coarse client family derived from the User-Agent (for example "browser", "curl" or "claude-code"). It does **not** log your IP address, API key or cookies with these events. They are used to improve ranking and to find searches that return nothing, and are deleted after 14 days.
- **Aggregate metrics.** Counters such as searches per minute, downloads per source, page views per page and per-source error rates. They contain no search text and no personal data, and are kept for 10 days. Their totals are public on the [usage statistics](https://3d.shep.bot/stats) page.
- **Request logs.** Like any website, the hosting infrastructure keeps standard request logs (which include IP addresses and User-Agents) for security and operations. Logs collected centrally are deleted after 14 days.
- **Rate limiting.** To keep the free service fair, the server counts requests per client IP address in memory for one minute at a time. These counters are never written to disk.

## What stays in your browser

The website stores two optional preferences in your browser's local storage: your light/dark theme choice and, only on self-hosted servers that require one, the API key you entered. Neither is sent anywhere except the API key, which goes back to the same server.

## Third parties you contact

- **Thumbnails** load directly from the asset sites (Poly Haven, ambientCG, BlenderKit and others), so those sites see your IP address when you browse results.
- **Downloads** of single files redirect to the source's CDN. Multi-file zips are assembled by this server from the source files.
- **Links** to source pages take you to those sites, which have their own privacy policies.

## Your choices and contact

Because no account or profile exists, there is nothing to export or delete for an individual visitor beyond the time-limited logs above. Questions or requests: see [Contact](https://3d.shep.bot/contact). This policy may change as the service evolves; the current version always lives at https://3d.shep.bot/privacy.

---
Source: https://3d.shep.bot/privacy