Scene

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

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

• 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

Contributors

Star history

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.

• 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