@three-ws/scene-mcp

@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. 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

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.
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 POST /api/diorama {action:"save"} to mint a shareable permalink at https://three.ws/diorama?id=….

Input parameters

compose_scene — prompt (required, 3–1024 chars: one sentence describing the world).

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"
}

Requirements

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

Environment variables

Variable	Required	Default
THREE_WS_BASE	no	https://three.ws
THREE_WS_TIMEOUT_MS	no	45000

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}