sozai-search-mcp

English | 日本語 | 简体中文 | 한국어 | Português | Español

Quick start · Tools · Sources · Semantic search · FAQ · ⭐ Star

Sozai Search MCP gives Claude Code, Claude Desktop, Cursor and any other MCP client a library of 39,000 free 3D assets: photoreal models, PBR materials and HDRIs from Poly Haven and ambientCG, low-poly game models from Kenney, Quaternius, KayKit and Polygonal Mind, rigged VRM avatars from Open Source Avatars, NASA spacecraft, rovers and telescopes, and Quixel Megascans listings. Ask for "a wooden crate under 1 m tall" or "a mossy rock"; the agent searches by words or by meaning, looks at the previews, and drops the files into your project, at their real size in metres. (Sozai, 素材, means "materials" in Japanese.)

Sozai Search is an index. It hosts no asset files: every result points at the official source, and files are downloaded from there by your own machine.

✨ Highlights

• Looks before it picks: view_assets shows the agent up to 8 previews, so it chooses by eye, not by title.
• Arrives at the right size: kit models are calibrated to metres (a door is 2.1 m, a person 1.75 m) and delivered already scaled; rigs and animations keep working.
• Light: the server is standard-library Python with no runtime dependencies. It starts in about 25 ms, idles at about 23 MB and holds no state between calls.
• Safe with untrusted data: https only, to the libraries' own hosts; every path stays inside the folder you gave; it never deletes your files.

🧭 How it works

"a wooden crate under 1 m tall"
   └─ search_assets   keywords + meaning, filtered by kind, size, height, polycount, licence
   └─ view_assets     the agent looks at the candidates' previews
   └─ fetch_asset     downloads from Poly Haven / ambientCG (or your local kit zip),
                      packs one .glb at real scale, appends the credit to CREDITS.md

sozai build downloads the published data once: one zip with every library's records (what each asset is, its size, licence and where to get it) and the search vectors. No asset files, no previews.

🚀 Quick start

🤖 Install with your AI agent

Give this repository's URL to Claude Code, Codex or another agent and ask it to install Sozai Search MCP. These are the steps it should follow (they work by hand too):

1. uv: check uv --version; if uv is missing, install it:

   • macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Register the server: run this in the user's own project folder. No clone is needed: uv fetches Sozai Search from GitHub.

   # Claude Code: this project only (writes .mcp.json)
   claude mcp add sozai -s project -- uvx --from git+https://github.com/kanaworksai-hue/sozai-search-mcp sozai
   
   # Codex: all projects (writes ~/.codex/config.toml)
   codex mcp add sozai -- uvx --from git+https://github.com/kanaworksai-hue/sozai-search-mcp sozai
   

   Other clients (Claude Desktop, Cursor, ...) take the same command in their JSON config:

   {"mcpServers": {"sozai": {"command": "uvx", "args": ["--from", "git+https://github.com/kanaworksai-hue/sozai-search-mcp", "sozai"]}}}
   

3. Start a new session: MCP servers load when a session starts. Claude Code asks once to approve the project's .mcp.json. Check with claude mcp list or codex mcp list.

4. Try it: search for "wooden crate". The first search downloads the published data (about 15 MB) and builds the index in a few seconds. Give fetch_asset an absolute folder inside the project.

5. Search by meaning (optional, ask the user first): it makes descriptive queries and queries in any language much better (in our tests the right asset comes first 79% of the time instead of 31%). It needs about 600 MB of disk once: about 250 MB of Python packages and the 350 MB query model. Ask the user whether to turn it on; if they agree, download the query model:

   uvx --from "sozai-search-mcp[semantic] @ git+https://github.com/kanaworksai-hue/sozai-search-mcp" sozai semantic-setup
   

   Then register with --from "sozai-search-mcp[semantic] @ git+https://github.com/kanaworksai-hue/sozai-search-mcp" in place of --from git+https://github.com/kanaworksai-hue/sozai-search-mcp.

🛠️ From a clone

You need uv (it brings Python 3.10 or newer).

git clone https://github.com/kanaworksai-hue/sozai-search-mcp
cd sozai-search-mcp
uv sync
uv run sozai build            # downloads the published data (one zip, no asset files) and indexes it
uv run sozai search "wooden crate" --kind model
uv run sozai fetch polyhaven:wooden_crate_01 ./assets --quality web

Claude Code (registered for one project only):

claude mcp add sozai -s project -- uv run --directory /path/to/sozai-search-mcp sozai

Any other MCP client (Claude Desktop, Cursor, ...):

{
  "mcpServers": {
    "sozai": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sozai-search-mcp", "sozai"]
    }
  }
}

Without a clone, uv can run it straight from GitHub: uvx --from git+https://github.com/kanaworksai-hue/sozai-search-mcp sozai. The first search builds the index if sozai build has not run yet. Give fetch_asset an absolute folder: an MCP server does not run in your project folder.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗