Skip to content
nirholasPublic

About

MCP server that turns one sentence into a placed 3D diorama and exports it as a single GLB. No API key.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

three.ws

@three-ws/scene-mcp

Speak 3D worlds into being: turn one sentence into a placed diorama from any AI agent.

npm license node MCP Registry three.ws


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

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.

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

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

Links


Part of the three.ws SDK suite: 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub

Support the project

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

Built for AI agents too

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.

More from the same author

Contributors

Contributors

Star history

Star History Chart

Part of three.ws

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.

About

MCP server that turns one sentence into a placed 3D diorama and exports it as a single GLB. No API key.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

⌂ 换网址