@three-ws/scene-mcp
Speak 3D worlds into being — turn one sentence into a placed diorama from any AI agent.
---
> A [Model Context Protocol](https://modelcontextprotocol.io) 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
```bash
npm install @three-ws/scene-mcp
```
Or run with `npx` (no install):
```bash
npx @three-ws/scene-mcp
```
## Quick start
**Claude Code**, one line:
```bash
claude mcp add scene -- npx -y @three-ws/scene-mcp
```
**Claude Desktop / Cursor** (`claude_desktop_config.json` or `mcp.json`):
```json
{
"mcpServers": {
"scene": {
"command": "npx",
"args": ["-y", "@three-ws/scene-mcp"]
}
}
}
```
Inspect the surface with the MCP Inspector:
```bash
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
```jsonc
// 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](./LICENSE)
---
Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub
## License
All rights reserved. See [LICENSE](LICENSE).
## Star History
[](https://www.star-history.com/#nirholas/3d-scene-mcp&Date)
## Support the project
If 3d-scene-mcp saves you time, **[star it on GitHub](https://github.com/nirholas/3d-scene-mcp)**. 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](https://twitter.com/intent/tweet?text=3d-scene-mcp%3A%20Build%20and%20manipulate%203D%20scenes%20from%20natural%20language%20via%20AI%20agents&url=https%3A%2F%2Fgithub.com%2Fnirholas%2F3d-scene-mcp) · [Share on Bluesky](https://bsky.app/intent/compose?text=3d-scene-mcp%3A%20Build%20and%20manipulate%203D%20scenes%20from%20natural%20language%20via%20AI%20agents%20https%3A%2F%2Fgithub.com%2Fnirholas%2F3d-scene-mcp) · [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2Fnirholas%2F3d-scene-mcp) · [Submit to Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fgithub.com%2Fnirholas%2F3d-scene-mcp&t=3d-scene-mcp%3A%20Build%20and%20manipulate%203D%20scenes%20from%20natural%20language%20via%20AI%20agents) · [Share on Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fnirholas%2F3d-scene-mcp&title=3d-scene-mcp%3A%20Build%20and%20manipulate%203D%20scenes%20from%20natural%20language%20via%20AI%20agents)
## Built for AI agents too
Coding agents and LLM tooling can read this repo directly: [AGENTS.md](./AGENTS.md), [llms.txt](./llms.txt), [llms-full.txt](./llms-full.txt). Point an agent at `https://github.com/nirholas/3d-scene-mcp` and it has the context it needs.
## More from the same author
- [All repositories by nirholas](https://github.com/nirholas/nirholas#readme): the full catalog, grouped by topic
- [three.ws](https://three.ws): the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
- Questions or ideas: [open an issue](https://github.com/nirholas/3d-scene-mcp/issues) or [start a discussion](https://github.com/nirholas/3d-scene-mcp/discussions)
## Contributors
[](https://github.com/nirholas/3d-scene-mcp/graphs/contributors)