Speak 3D worlds into being: turn one sentence into a placed diorama from any AI agent.
A Model Context Protocol server that gives any AI assistant the three.ws diorama pipeline over stdio. Describe a world in a sentence and
compose_scenereturns a placed plan (mood, palette, ground, and a set of single-object forge prompts), ready to build into an orbitable 3D scene.build_worldcollapses the whole pipeline (compose → forge every object → merge) into one call for agents with no browser to drive it.export_scenemerges an already-forged diorama into one glTF 2.0 binary (every object a named, selectable node, plus ground and mood-tuned lighting), ready to open in Scene Studio. Browse saved worlds withget_sceneandlist_scenes.
This is the companion to the three.ws avatar one-liner: avatars give you a character; scenes give you a world. No API key, no signer, no payment: every call hits the public /api/diorama endpoint.
npm install @three-ws/scene-mcpOr run with npx (no install):
npx @three-ws/scene-mcpClaude Code, one line:
claude mcp add scene -- npx -y @three-ws/scene-mcpClaude Desktop / Cursor (claude_desktop_config.json or mcp.json):
{
"mcpServers": {
"scene": {
"command": "npx",
"args": ["-y", "@three-ws/scene-mcp"]
}
}
}Inspect the surface with the MCP Inspector:
npx -y @modelcontextprotocol/inspector npx @three-ws/scene-mcp| Tool | Type | What it does |
|---|---|---|
compose_scene |
generative | One sentence → a diorama plan: title, mood, palette, ground, and 2-8 placed single-object forge prompts. |
build_world |
generative | One sentence → a fully forged, exported 3D world in one call: compose → forge every object (free lane) → merge into one GLB. No browser needed; can take a couple of minutes. |
export_scene |
generative | Merge an already-forged diorama (objects with real glbUrls) into one glTF 2.0 binary (named, selectable nodes plus ground and mood-tuned lighting), ready for Scene Studio. |
get_scene |
read-only | Fetch a saved world by id (with GLB URLs) and its orbitable viewer URL. |
list_scenes |
read-only | Browse the recent or featured diorama gallery. |
compose_scene returns only the plan: no meshes are forged and nothing is saved. Forge each object via /api/forge, then either call export_scene yourself or POST /api/diorama {action:"save"} to mint a shareable permalink at https://three.ws/diorama?id=…. build_world does the compose-forge-export sequence for you in a single tool call. Both build_world and export_scene degrade gracefully on partial failure: objects that never forge are skipped and named in the response's skipped array; the rest of the world still exports.
compose_scene: prompt (required, 3-1024 chars: one sentence describing the world).
build_world: prompt (required, 3-1024 chars: one sentence describing the world).
export_scene: diorama (required: the diorama object returned by compose_scene/get_scene, with each object to include carrying status:"ready" and a real glbUrl).
get_scene: id (required: the diorama id returned at save time).
list_scenes: list (recent | featured, default recent), limit (1-50, default 24).
// build_world: the whole pipeline in one call
> { "prompt": "a neon alley with a food cart and two streetlights" }
{
"ok": true,
"diorama": { "title": "Neon Alley", "mood": "night", /* ...forged objects with real glbUrl values... */ },
"object_count": 4,
"ready_count": 4,
"glb_url": "https://storage.googleapis.com/.../scene-neon-alley.glb",
"scene_studio_url": "https://three.ws/scene?model=https%3A%2F%2Fstorage.googleapis.com%2F...%2Fscene-neon-alley.glb",
"exported_count": 4,
"skipped": []
}- Node.js >= 20.
- Network access to
https://three.ws(or your ownTHREE_WS_BASE).
| Variable | Required | Default |
|---|---|---|
THREE_WS_BASE |
no | https://three.ws |
THREE_WS_TIMEOUT_MS |
no | 45000 |
- Homepage: https://three.ws
- Changelog: https://three.ws/changelog
- Issues: https://github.com/nirholas/three.ws/issues
- License: Apache-2.0, see LICENSE
Part of the three.ws SDK suite: 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub
If scene-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/scene-mcp and it has the context it needs.
- All repositories by nirholas: the full catalog, grouped by topic
- three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
- Questions or ideas: open an issue or start a discussion
three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/scene-mcp is one package from it.
- Documentation site: https://nirholas.github.io/scene-mcp/
- npm: https://www.npmjs.com/package/@three-ws/scene-mcp
- Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of
packages/scene-mcp) - Agent-readable summary: llms.txt and AGENTS.md
- Issues and ideas: https://github.com/nirholas/scene-mcp/issues