sand3d-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SAND3D_WAKE_SECONDS | No | Sets how long the first request waits for the Sandflow space to load the catalog if it is asleep (up to 4 minutes by default). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Search and download ready 3D objects (GLB plus the Python program that builds them) from the open Sand3D catalog by Sandflow, about 100k objects under CC BY 4.0. Workflow: translate the request to English and describe how the thing looks, call search_objects, look at the numbered contact sheet image to pick (names repeat a lot), refine with find_similar, then download_object into the user's project folder. For moving parts search the articraft dataset or set only_with_joints. Read sand3d_format_guide before writing three.js or game code for a downloaded model. The service is a single CPU space run by Sandflow: dozens of objects are fine, bulk downloads belong to the open Hugging Face datasets Sandflow/sand3d-*.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_objectsA | Search the Sand3D catalog (about 100k 3D objects with GLB, render and generating Python program, CC BY 4.0). Default mode compares an English text description with the renders (CLIP), so describe the look in English, e.g. 'old red farm tractor'. match_words=true does exact keyword search in names, families, attribution and program code. Returns a numbered text list with object ids and a contact sheet image with the same numbers; names repeat a lot, so pick by the image. Runs against a free single-CPU space by Sandflow: fine for dozens of objects; for bulk work use the open Hugging Face datasets Sandflow/sand3d-*. |
| find_similarA | Find objects that look like a given Sand3D object (visual nearest neighbours). Returns a numbered list and a contact sheet image. Runs against a free single-CPU space by Sandflow: fine for dozens of objects; for bulk work use the open Hugging Face datasets Sandflow/sand3d-*. |
| get_objectA | Get the card of one Sand3D object: name, dataset, family, parts, joints, license, attribution string, page URL, and its generating Python program (sand3d library, millimeters, Z up). The program is cut to program_lines unless full_program=true. |
| download_objectA | Download one Sand3D object into a folder the user chose: model.glb, program.py, render.png (512x512, transparent) and meta.json with license and attribution; model.usda too when include_usda=true or when the object has no GLB. Files go to /; existing files with the same names are overwritten. Returns paths, sizes, GLB stats (meters, Y up), part names, joints and the attribution string to credit (CC BY 4.0). include_threejs_helper=true also writes s3d-joints.js (collectJoints, setJoint, setJoint01, fitToHeight). Only writes inside the given directory. Runs against a free single-CPU space by Sandflow: fine for dozens of objects; for bulk work use the open Hugging Face datasets Sandflow/sand3d-*. |
| list_datasetsA | List Sand3D datasets (objaverse household items, cad mechanical parts, articraft articulated objects, simready warehouse assets, automate mechanical assemblies) with object counts and their families. Pass dataset to see all families of one dataset; family keys or labels can be used in search_objects. |
| sand3d_format_guideA | How Sand3D GLB files are built (meters, Y up, root scale 0.001, part names, materials), how joints are stored in extras.s3d_joint and how to move them in three.js, the program format, licenses and fair use. Read before writing code that loads a downloaded model. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| sand3d-format-guide | Sand3D GLB format, joints, three.js usage, licenses and fair use. |
TDQS
Scored across 6 tools
Each tool has a clearly distinct role: text/visual catalog search (search_objects), visual nearest-neighbour lookup (find_similar), single-object metadata (get_object), file export (download_object), catalog structure (list_datasets), and reference docs (sand3d_format_guide). The only close pair, search_objects vs find_similar, is separated by input type (English description vs an existing object id) and both are explicitly documented. An agent can select correctly without guessing.
Five of six tools follow a clean verb_noun snake_case pattern (search_objects, find_similar, get_object, download_object, list_datasets). The exception is sand3d_format_guide, a noun-phrase documentation tool, which is a minor but understandable deviation since it is not an action on the catalog.
Six tools is well within the ideal 3-15 range and each earns its place: search, similarity, detail, download, dataset listing, and format guidance. There is no redundancy and no filler tool.
The surface covers the full discover-inspect-download lifecycle plus licensing/attribution info and a code-format guide, with bulk access routed to Hugging Face datasets. Minor gaps remain, such as no direct way to paginate or enumerate all objects in a family beyond keyword search, and no dedicated attribution/licence lookup separate from get_object.