You install and run CHUK’s 3D Scene & Camera MCP Server to orchestrate 3D worlds, cinematography, and physics-driven animation. This server sits between physics simulations and motion rendering, letting you author scenes, bake physics into keyframes, and export ready-to-render artifacts for video and interactive viewers.

How to use

You use a client to connect to the stage server and perform four core activities: authoring a scene, configuring the camera, binding objects to physics, and baking the physics into bake data that you can export. After baking, you can export the scene to formats used by R3F, Remotion, or glTF. The server returns artifact URIs that point to stored scene data, baked animations, and export artifacts.

How to install

Prerequisites: you need Python and a suitable runtime for MCP, plus optional tooling for running the UI client (e.g., Claude Desktop) if you plan to test with that.

# Install directly from public URL with uvx (recommended)
uvx stage.chukai.io/mcp

# Install from PyPI
pip install chuk-mcp-stage

# Install from source
cd chuk-mcp-stage
pip install -e .

Other important notes

Physics uses the Rapier engine by default via a public service. You can configure the Rapier service URL and timeouts through environment variables. The server supports multiple transport modes: stdio (default, MCP protocol via stdin/stdout), http (REST API on port 8000), and streamable (Server-Sent Events for streaming responses). You can run with the following commands to choose the mode.

# STDIO mode (default)
uv run chuk-mcp-stage

# HTTP mode (REST API on port 8000)
uv run chuk-mcp-stage http

# Streamable mode (Server-Sent Events)
uv run chuk-mcp-stage streamable

Configuration with MCP client (Claude Desktop example)

Add a stage MCP server configuration to your Claude Desktop client to connect to the stage server. You can point to a public URL or use a local installation.

{
  "mcpServers": {
    "stage": {
      "command": "uvx",
      "args": ["stage.chukai.io/mcp"],
      "env": {
        "RAPIER_SERVICE_URL": "https://rapier.chukai.io"
      }
    }
  }
}

Physics integration and modes

Stage integrates with physics simulations via chuk-mcp-physics and the Rapier engine. There are three integration methods: direct Rapier HTTP (default), via MCP Tools, and a hybrid approach. You can configure the Rapier service URL and timeout with environment variables.

# Environment variables (defaults shown)
RAPIER_SERVICE_URL=https://rapier.chukai.io
RAPIER_TIMEOUT=30.0
PHYSICS_PROVIDER=auto  # or rapier, mcp

{
  "mcpServers": {
    "stage": {
      "command": "chuk-mcp-stage",
      "env": {
        "RAPIER_SERVICE_URL": "http://localhost:9000",
        "RAPIER_TIMEOUT": "60.0"
      }
    },
    "physics": {
      "command": "uvx",
      "args": ["chuk-mcp-physics"],
      "env": {
        "RAPIER_SERVICE_URL": "http://localhost:9000"
      }
    }
  }
}

Public Rapier Service URL is https://rapier.chukai.io and requires no authentication for prototyping.

Google Drive OAuth storage in HTTP mode

When running in HTTP mode, you can store scenes in Google Drive using OAuth 2.1. This keeps data user-owned and securely stored in Drive. The flow requires a Google Cloud project with Drive API enabled and OAuth credentials.

# Example package installation (with Google Drive support)
pip install "chuk-mcp-stage[google_drive]"

# Example environment (fill with real credentials)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

uv run chuk-mcp-stage http

OAuth endpoints are exposed when running in HTTP mode

Authorization: http://localhost:8000/oauth/authorize

Token: http://localhost:8000/oauth/token

## Storage and artifacts model

Scenes, baked animations, and exports are stored as artifacts in a workspaces-based Virtual File System (VFS). You reference artifacts by URIs rather than inline data, enabling clean separation between scene metadata and large payloads.

Example artifact URIs

scene: artifact://stage/demo-xyz/scene.json animations: artifact://stage/demo-xyz/animations/ball.json export/r3f: artifact://stage/demo-xyz/export/r3f/Scene.tsx

## Core concepts and workflow overview

There are two phases in a typical use case: authoring (define the world) and baking (generate animation data). Authoring creates the scene graph with objects, lights, cameras, and physics bindings. Baking connects to a physics simulation, samples states over time, and stores keyframes. You then export to formats for rendering or playback.

Authoring: create scene, add objects, set environment

scene = await stage_create_scene(name="demo") await stage_add_object(scene_id=scene.scene_id, object_id="ground", object_type="plane") await stage_add_object(scene_id=scene.scene_id, object_id="ball", object_type="sphere", radius=1.0) await stage_set_environment(scene_id=scene.scene_id, environment_type="gradient", lighting_preset="three-point")

Baking: bake simulation to keyframes

await stage_bake_simulation(scene_id=scene.scene_id, simulation_id="sim1", fps=60, duration=10.0)

## Export formats

Export the scene and its baked animations to R3F components, Remotion projects, glTF, or JSON. The exports are returned as artifact URIs so you can share or route them to other tools.

result = await stage_export_scene(scene_id=scene.scene_id, format="remotion-project", output_path="/export/remotion")

## Example workflow and quick-start examples

Start with a simple falling ball, then add a camera shot and export to Remotion to see the end-to-end pipeline.

1. Create scene

scene = await stage_create_scene(name="falling-ball-demo", description="Ball falling under gravity")

2. Add ground and ball

await stage_add_object(scene_id=scene.scene_id, object_id="ground", object_type="plane", size_x=20.0, size_y=20.0, material_preset="metal-dark") await stage_add_object(scene_id=scene.scene_id, object_id="ball", object_type="sphere", radius=1.0, position_y=5.0, material_preset="glass-blue")

3. Orbit camera shot

await stage_add_shot(scene_id=scene.scene_id, shot_id="orbit-shot", camera_mode="orbit", focus_object="ball", orbit_radius=8.0, orbit_elevation=30.0, orbit_speed=0.1, start_time=0.0, end_time=10.0)

4. Export to Remotion

result = await stage_export_scene(scene_id=scene.scene_id, format="remotion-project")

## Example outputs and next steps

You can inspect artifact URIs for the scene, its exports, and animations, then feed those into your rendering or playback tools. The system is designed to let you iterate quickly from authoring to baking to exporting.

## Tip: two-phase model recap

Authoring is declarative: you define what should exist and how it should be connected. Baking is computational: the physics oracle computes motion and stores it as keyframes.

## Available tools

### stage\_create\_scene

Create a new scene and define its metadata.

### stage\_add\_object

Add a 3D object to the scene with geometry, transforms, and material.

### stage\_set\_environment

Configure scene lighting and environmental settings.

### stage\_add\_shot

Define camera paths and shot timing for cinematography.

### stage\_bind\_physics

Link a scene object to a physics body.

### stage\_bake\_simulation

Bake a physics simulation into keyframes.

### stage\_export\_scene

Export the scene and baked data to various formats.

### stage\_get\_scene

Retrieve the complete scene data.

### vfs\_ls

List files in the virtual filesystem-backed storage.

### vfs\_read

Read a file from the virtual filesystem-backed storage.

### vfs\_cp

Copy assets within the storage system.

### r3f\_preview\_scene

Preview an exported R3F scene in a browser.

### motion\_apply\_spring

Apply spring dynamics to baked keyframes for animation refinements.