three.ws Scenes

@three-ws/scene-mcp

用语言创造 3D 世界：让任何 AI Agent 用一句话生成摆放好的立体场景。

---

一个通过 stdio 为任何 AI 助手提供 three.ws 立体场景流水线的 Model Context Protocol 服务。用一句话描述一个世界，compose_scene 就会返回一份摆放方案（氛围、调色板、地面和一组用于生成单个对象的提示词），可直接用于构建可环绕查看的 3D 场景。build_world 将整个流水线（compose → forge 每个对象 → merge）合并为一次调用，适用于没有浏览器可操作的 Agent。export_scene 会将已生成的立体场景合并为一个 glTF 2.0 二进制文件（每个对象都是带名称、可选择的节点，另含地面和根据氛围调整的光照），可直接在 Scene Studio 中打开。使用 get_scene 和 list_scenes 浏览已保存的世界。

这是 three.ws 头像一句话生成工具的配套服务：头像为你生成一个角色，场景则为你生成一个世界。无需 API 密钥、签名者或付款：每次调用都会访问公开的 /api/diorama 端点。

安装

npm install @three-ws/scene-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/scene-mcp

快速开始

Claude Code，一行命令：

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

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"scene": {
			"command": "npx",
			"args": ["-y", "@three-ws/scene-mcp"]
		}
	}
}

使用 MCP Inspector 检查工具界面：

npx -y @modelcontextprotocol/inspector npx @three-ws/scene-mcp

工具

工具	类型	功能
compose_scene	生成式	一句话 → 一份立体场景方案：标题、氛围、调色板、地面，以及 2-8 个摆放好的单对象生成提示词。
build_world	生成式	一句话 → 一次调用生成并导出完整的 3D 世界：compose → forge 每个对象（免费通道）→ 合并为一个 GLB。无需浏览器；可能需要几分钟。
export_scene	生成式	将已生成的立体场景（含真实的 glbUrl 的对象）合并为一个 glTF 2.0 二进制文件（带名称、可选择的节点，以及地面和根据氛围调整的光照），可直接在 Scene Studio 中打开。
get_scene	只读	按 id 获取已保存的世界（含 GLB URL）及其可环绕查看的查看器 URL。
list_scenes	只读	浏览近期或精选的立体场景图库。

compose_scene 只返回方案：不会生成网格，也不会保存任何内容。通过 /api/forge 生成每个对象，然后自行调用 export_scene，或使用 POST /api/diorama {action:"save"} 生成可分享的永久链接 https://three.ws/diorama?id=…。build_world 会通过一次工具调用为你完成 compose-forge-export 流程。build_world 和 export_scene 都能妥善处理部分失败：无法生成的对象会被跳过，并列入响应中的 skipped 数组；其余部分仍会导出。

输入参数

compose_scene：prompt（必填，3-1024 个字符：用一句话描述世界）。

build_world：prompt（必填，3-1024 个字符：用一句话描述世界）。

export_scene：diorama（必填：由 compose_scene/get_scene 返回的立体场景对象，且其中每个待导出的对象都必须包含 status:"ready" 和有效的 glbUrl）。

get_scene：id（必填：保存时返回的立体场景 ID）。

list_scenes：list（recent | featured，默认值为 recent），limit（1-50，默认值为 24）。

示例

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

要求

• Node.js >= 20。
• 可访问网络 https://three.ws（或使用你自己的 THREE_WS_BASE）。

环境变量

变量	必填	默认值
THREE_WS_BASE	否	https://three.ws
THREE_WS_TIMEOUT_MS	否	45000

链接

• 主页：https://three.ws
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，参见 LICENSE

---

_{属于 three.ws SDK 套件：3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}