worldlabs-mcp
worldlabs-mcp is an MCP gateway to World Labs Marble that generates navigable 3D worlds from text, images, or video, manages them, and layers spatial audio/voice into a streaming viewer.
Generate 3D worlds from a text prompt, public image URL, 360ยฐ panorama, multi-image set with azimuth angles, or public video URL.
Upload local media end-to-end via
upload_and_generate, or manually withprepare_media_upload(signed GCS URL) thengenerate_world_from_media_asset.Track generation jobs with
get_operationfor polling orwait_for_worldfor blocking waits (default 90s timeout).Manage worlds: list, fetch details, and permanently delete worlds plus their assets (
list_worlds,get_world,delete_world).View worlds as rich cards with thumbnails, status badges, model labels, asset download links (SPZ splats, GLB mesh, panorama), and Marble viewer links (
show_worlds_card,show_world_card).Add spatial scene elements: positional audio/ambience (
broadcast_spatial_audio), a virtual TV playing Veo 3.1 video (place_world_tv), and a grounded animated avatar (spawn_agent_avatar).Narrate locations in the 3D world via TTS spatial voice notifications (
broadcast_spatial_notification).Refine prompts into Marble-optimised descriptions using a local Ollama model (
refine_with_local_llm).Explore the public Marble community gallery to browse by tag, fetch world details, mine original prompts, and run keyword searches (
gallery_explore).Get built-in docs covering all tools, models, workflows, and World Labs context at quick/standard/verbose detail (
worldlabs_help).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@worldlabs-mcp Create a 3D world from 'snowy mountain village at dusk'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
worldlabs-mcp (v0.5.1)
MCP gateway to World Labs Marble + Spark 2.0. Generate navigable 3D worlds from text, images, panoramas, multi-view sets, or video; view them with a streaming Gaussian-splat renderer; and ground a voice agent in scene coordinates.
Install (Claude Desktop, Windows)
irm https://github.com/sandraschi/worldlabs-mcp/releases/latest/download/install.ps1 | iexClaude-only one-liner: downloads the released worldlabs-mcp.mcpb bundle and
registers it in Claude Desktop. For every other client (Cursor, Antigravity,
OpenCode, Claude Code), add the stdio server manually with uvx:
{
"mcpServers": {
"worldlabs-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sandraschi/worldlabs-mcp", "worldlabs-mcp"],
"env": { "WORLDLABS_API_KEY": "<your-key>" }
}
}
}Related MCP server: Runware MCP
Table of Contents
๐ Setup & Quick Start โ install, API key, launch
๐ Features & Tools โ 21 MCP tools, generation modes, spatial voice agent, export pipelines, Marble Community Gallery (browse/search public worlds + prompt mining)
๐ Marble Adventure โ Godot 4.4 agent-built gallery; 5+3 Marble portals with hub life (plants, lamps, beacon); launch from the webapp Apps page; itch draft ยท MCD
๐๏ธ Architecture โ system design, ports, data flow
๐ฏ Prompt Engineering Guide โ artist styles, landmarks, materials, categories
๐ฅฝ VR & WebXR โ Quest, Pico 4, Vive streaming
๐๏ธ Spatial Voice & TTS โ edge-tts narration, audio spatialization
โก Spark 2.0 Renderer โ LoD splat tree,
.RADstreaming, virtual paging๐ฎ DCC Export โ Blender, Unity3D, Resonite pipelines
๐ World Modeling โ spatial intelligence landscape
Quickest Start
git clone https://github.com/sandraschi/worldlabs-mcp
cd worldlabs-mcp
just bootstrap
just serveOpens the web dashboard at http://localhost:10864. Get your API key at platform.worldlabs.ai/api-keys.
Ports
Port | Service |
10864 | Frontend (Vite webapp โ dashboard, library, Marble Gallery, Reality Hub) |
10865 | Backend bridge (FastAPI REST |
32400 | Plex server (optional; Cinema Worlds โ |
Stack: FastMCP 3.4+ (Python) ยท FastAPI ยท Vite + React + Tailwind ยท Tauri 2.0 NSIS native build (native/).
MIT License โข Maintained by sandraschi. Not affiliated with World Labs.
Available Tools
21 toolsbroadcast_spatial_audioA
Broadcast spatial audio (Music/Ambience) to the scene.
Pass a URL to an audio file (mp3, wav) to play it at the given 3D coordinate. The audio is spatialised via WebAudio PannerNode in the Spark viewer.
Inputs: prompt_or_url (required), x, y, z, +1 more. Returns: result
broadcast_spatial_notificationB
Broadcast a spatial voice notification to the active World Labs Spark Viewer. Connects to the Spatial Voice Agent to narrate specific locations in the 3D world.
Inputs: text (required), x, y, z. Returns: result
delete_worldA
Delete a previously generated world by its ID.
Permanently removes the world and all its associated assets (splat files, mesh, panorama, thumbnail) from the Marble API. This action cannot be undone.
Inputs: world_id (required). Returns: object
gallery_exploreA
Explore the public Marble community gallery (marble.worldlabs.ai).
[RATIONALE] The gallery is a public showcase of community-generated worlds with full original prompts, seeds, and asset URLs. One portmanteau keeps prompt mining, browsing, world detail lookups, and keyword search under a single tool.
Return Format
{"success": bool, "message": str, "operation": str, "data": {"tag", "entries": [...], "next_page_token", "count"} | {"world": {...}} | {"query", "searched", "matched", "entries": [...]}}
Examples
gallery_explore(operation="browse", tag="fantasy", page_size=10) gallery_explore(operation="world", world_id="8a62c661-aaf2-41fe-a980-f9bef671dcea") gallery_explore(operation="prompts", tag="curated", page_size=20) gallery_explore(operation="search", query="vienna") gallery_explore(operation="search", query="cyberpunk alley", tag="all", page_size=5)
Inputs: operation (required), tag, query, world_id, +3 more. Returns: object
generate_world_from_imageB
Generate a 3D world from a public image URL.
Returns immediately with an operation_id.
Inputs: image_url (required), seed, tags, model, +4 more. Returns: object
generate_world_from_media_assetB
Generate a world from a previously uploaded media asset.
Inputs: kind (required), media_asset_id (required), model, is_panorama, +2 more. Returns: object
generate_world_from_multi_imageB
Generate a 3D world from multiple images at specified azimuth angles.
Inputs: image_urls (required), azimuths_deg (required), model, text_prompt, +1 more. Returns: object
generate_world_from_textA
Generate a 3D world from a text description.
Returns immediately with an operation_id. Use get_operation to check status, or wait_for_world for blocking poll (โค90s by default).
Inputs: text_prompt (required), seed, tags, model, +1 more. Returns: object
generate_world_from_videoB
Generate a 3D world from a public video URL.
Returns immediately with an operation_id.
Inputs: video_url (required), seed, tags, model, +3 more. Returns: object
get_operationA
Poll a generation operation for its current status.
Recommended for long-running jobs (marble-1.1-plus, auto-expanding, multi-minute). Call repeatedly until done=True rather than using wait_for_world.
Inputs: operation_id (required). Returns: object
get_worldB
Fetch the latest details for a generated world by its ID.
Inputs: world_id (required). Returns: object
list_worldsB
List previously generated worlds.
Inputs: page_size, page_token. Returns: object
place_world_tvC
Place a virtual TV screen in the 3D world playing a Veo 3.1 video.
Inputs: video_url (required), x, y, z, +2 more. Returns: result
prepare_media_uploadA
Prepare a signed GCS upload URL for a local file.
After calling this, PUT the raw file bytes to upload_info.upload_url with the returned upload_info.headers, then pass media_asset.id to generate_world_from_media_asset. For a simpler flow, use upload_and_generate.
Inputs: kind (required), extension (required), file_name (required). Returns: object
refine_with_local_llmA
Refine a world prompt using a local Ollama model.
Sends a short prompt to Ollama for expansion into a detailed, Marble-optimised 3D world generation prompt.
Inputs: prompt (required), model, style. Returns: object
show_world_cardA
Display a single world as a rich detail card with assets and viewer link.
Shows the world thumbnail, AI caption, model used, creation date, all available asset download links (SPZ splats at 100k/500k/full, collision mesh GLB, panorama), and a direct link to the Marble viewer. Equivalent to get_world but rendered as a Prefab card.
Inputs: world_id (required).
show_worlds_cardA
Display generated worlds as a rich scannable card with thumbnail previews.
Lists worlds from your Marble account with status badges, model labels, dates, and direct viewer links. Equivalent to list_worlds but rendered as a Prefab card rather than raw JSON.
Inputs: page_size, page_token.
spawn_agent_avatarC
Materialize an animated agent avatar in the 3D scene. The viewer will attempt to ground the avatar on the collider mesh.
Inputs: x, y, z, rotation, +1 more. Returns: result
upload_and_generateA
Upload a local file and generate a 3D world from it (end-to-end).
Handles the full flow: prepare upload -> PUT file to GCS -> generate world. Returns immediately with an operation_id once upload completes.
Inputs: kind (required), local_file_path (required), model, is_panorama, +2 more. Returns: object
wait_for_worldA
Block-poll an operation until it completes, fails, or times out.
WARNING: Default timeout is 90 seconds to stay within MCP client limits. For marble-1.1-plus jobs (often multi-minute), use get_operation manually instead, or increase timeout_seconds explicitly (e.g. 600) if your client supports it.
Inputs: operation_id (required), timeout_seconds, poll_interval_seconds. Returns: object
worldlabs_helpA
World Labs MCP API reference โ three detail levels.
Returns structured documentation about every tool in this server, the Marble API models, typical workflow, and World Labs context.
Inputs: topic, detail. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 21 tools
Most tools are clearly separated by resource/action (generate vs list vs delete; text vs image vs video). The only overlaps are the card/JSON pairs (show_worlds_card/list_worlds, show_world_card/get_world) and get_operation/wait_for_world, but their descriptions explicitly call out when to use each, so misselection is unlikely.
Names are predominantly lowercase snake_case with a verb_noun structure, such as generate_world_from_text, list_worlds, and delete_world. A few exceptions like gallery_explore (noun_verb) and worldlabs_help (noun-only) keep it from being perfectly consistent.
21 tools is on the heavy side for a world-generation server. Several generation input variants plus duplicate card/JSON equivalents and auxiliary tools (help, local LLM refine) inflate the surface, though most tools serve a distinct real use case.
The core workflow is well covered: upload, generate from multiple media types, poll operations, list/get/delete worlds, and browse the gallery. Minor gaps existโno operation cancellation and no removal/stop for placed scene objects (TV, avatar, audio)โbut these are not blocking for the primary generation lifecycle.
Maintenance
Related MCP Connectors
Generate, edit, and deploy immersive 3D/WebGL web projects from any MCP assistant.
AI video, image and audio generation with 140+ AI models from any MCP agent
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.5 and more.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables Claude to generate 3D worlds from text, images, video, and multi-image inputs using the WorldLabs Marble API.-

Runware MCPofficial
AlicenseNot gradedqualityBmaintenanceMCP server that gives AI agents access to Runware's full API for image, video, audio, 3D, upscaling, and other media generation and processing tasks via natural language.663 npmMIT- AlicenseNot gradedqualityBmaintenanceEnables AI agents to procedurally generate, transform, inspect, and export 3D meshes and scenes through MCP tools.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables natural language control of Autodesk Maya through MCP, including scene queries, Python/MEL execution, viewport screenshots, tool invocation, and customizable body rigging.MIT