Skip to main content
Glama

FastMCP Version Ruff Linted with Biome Built with Just Marble Adventure

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 | iex

Claude-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, .RAD streaming, 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 serve

Opens 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 /api/* + MCP HTTP + SSE narration)

32400

Plex server (optional; Cinema Worlds โ€” PLEX_TOKEN in .env)

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 tools
broadcast_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

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

    A3.5/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers