three.ws Scenes

@three-ws/scene-mcp

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_scene returns a placed plan (mood, palette, ground, and a set of single-object forge prompts), ready to build into an orbitable 3D scene. build_world collapses the whole pipeline (compose → forge every object → merge) into one call for agents with no browser to drive it. export_scene merges 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 with get_scene and list_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.

Install

npm install @three-ws/scene-mcp

Or run with npx (no install):

npx @three-ws/scene-mcp

Quick start

Claude Code, one line:

claude mcp add scene -- npx -y @three-ws/scene-mcp

Claude 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

Tools

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.

Input parameters

`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).

Example

// compose_scene

{ "prompt": "a lonely lighthouse on a stormy cliff at dusk" }

{ "ok": true, "diorama": { "title": "Beacon at Dusk", "mood": "dusk", "ground": "stone", "island": "craggy", "palette": { "sky": ["#2b2350", "#c76b4a"], "ground": "#5b5560", "fog": "#3a3550", "accent": "#ffb27a" }, "objects": [ { "id": "obj-0", "label": "lighthouse", "prompt": "white-and-red striped stone lighthouse", "position": [0, 0, 0], "scale": 2.2, "rotationY": 0, "status": "pending", "glbUrl": null } ] }, "object_count": 1, "viewer_base": "https://three.ws/diorama" }

// 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": [] }

Requirements

• Node.js >= 20.
• Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

Links

• 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