# Marble WorldLabs MCP Server

An MCP (Model Context Protocol) server that provides Claude with direct access to the [WorldLabs Marble API](https://docs.worldlabs.ai/api) for generating 3D worlds from text, images, video, and multi-image inputs.

## Features

- **Text-to-World** — Generate 3D worlds from text descriptions
- **Image-to-World** — Generate from a single image (URL, base64, or uploaded file)
- **Video-to-World** — Generate from video
- **Multi-Image-to-World** — Generate from multiple images with azimuth positioning
- **Media Asset Management** — Upload local files and manage media assets
- **Operation Polling** — Check generation status with manual or automatic polling
- **World Management** — List, filter, and retrieve generated worlds
- **Full Model Support** — marble-1.1-plus, marble-1.1, marble-1.0, marble-1.0-draft

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Configure your API key

Create a `.env` file in the project root (or use an existing one):

```env
WLT_API_KEY=your_api_key_here
```

You can also use `WORLDLABS_API_KEY` as the variable name.

### 3. Build

```bash
npm run build
```

### 4. Add to Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "marble-worldlabs": {
      "command": "node",
      "args": ["c:\\path_to_project\\marble_worldlabs\\dist\\index.js"],
      "env": {
        "WLT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or if you prefer to use the `.env` file instead of inline env vars:

```json
{
  "mcpServers": {
    "marble-worldlabs": {
      "command": "node",
      "args": ["c:\\path_to_project\\marble_worldlabs\\dist\\index.js"]
    }
  }
}
```

### 5. Add to Claude Code (optional)

```bash
claude mcp add marble-worldlabs node "E:\SolSync\Projects\code stuff\marble_worldlabs\dist\index.js"
```

## Available Tools

| Tool | Description |
|------|-------------|
| `health_check` | Verify API connectivity |
| `generate_world_from_text` | Create a world from a text description |
| `generate_world_from_image_url` | Create a world from an image URL |
| `generate_world_from_image_base64` | Create a world from base64-encoded image data |
| `generate_world_from_video_url` | Create a world from a video URL |
| `generate_world_from_multi_image` | Create a world from multiple images with azimuth angles |
| `generate_world_from_media_asset` | Create a world from a previously uploaded media asset |
| `upload_local_file` | Upload a local image/video file as a media asset |
| `prepare_media_upload` | Get a signed upload URL for manual file uploads |
| `get_media_asset` | Get metadata for an uploaded media asset |
| `get_operation_status` | Check the status of a generation operation |
| `wait_for_operation` | Auto-poll an operation until it completes (~5 min) |
| `get_world` | Get full details and asset URLs for a world |
| `list_worlds` | List and filter your generated worlds |

## Typical Workflow

1. **Generate** — Use any `generate_world_from_*` tool to start world creation
2. **Wait** — Use `wait_for_operation` to auto-poll, or `get_operation_status` to check manually
3. **View** — Open the returned `world_marble_url` in a browser, or use `get_world` for asset URLs
4. **Download** — Use the asset URLs (splats, mesh, panorama) for your projects

## Models

| Model | Best for |
|-------|----------|
| `marble-1.1-plus` | Largest worlds, outdoor/large indoor spaces |
| `marble-1.1` | Default, good balance of quality and speed |
| `marble-1.0` | Previous generation |
| `marble-1.0-draft` | Fast drafts, lower quality |

## Notes

- World generation typically takes **~5 minutes**
- The API uses credits — check [pricing](https://docs.worldlabs.ai/api/pricing)
- Generated worlds can be viewed at `https://marble.worldlabs.ai/world/{world_id}`
- Asset URLs include Gaussian splats (SPZ format), collider meshes (GLB), and panorama images