---
name: rayscaper
description: Render, light and art-direct SketchUp models in Rayscaper through its MCP server (the rayscaper tools). Use when the user asks to change or judge a Rayscaper render, its materials, lights, sky, camera, scatters (grass, plants, trees) or look, to set up a model for rendering, to make render variations, or to set up the Rayscaper MCP server.
---

# Rayscaper

Rayscaper is a path tracer for SketchUp, with a standalone app for other scene files. While its render window is open
it runs an MCP server, and the `rayscaper` tools change the scene the user is looking at. The user watches the render
window while you work: a badge in its corner shows what you're doing, and they can stop your access there at any time.

## Connecting

The server is Streamable HTTP at `http://127.0.0.1:47390/mcp`, without a token. It only runs while Rayscaper's render
window is open (SketchUp: **Extensions > Rayscaper > Start Render**, or the standalone app). When that port was taken,
Rayscaper uses the next free one: every running Rayscaper writes its url to `mcp/instances/<pid>.json` in its profile
(`%APPDATA%\Rayscaper` on Windows, `~/Library/Application Support/Rayscaper` on a Mac, `~/.config/Rayscaper` on
Linux).

If the `rayscaper` tools are missing, register the server once for all projects and start a new session:

- Claude Code: `claude mcp add --scope user --transport http rayscaper http://127.0.0.1:47390/mcp`
- Codex: add to `~/.codex/config.toml`:
  ```toml
  [mcp_servers.rayscaper]
  url = "http://127.0.0.1:47390/mcp"
  ```
- Other apps: add a remote (Streamable HTTP) MCP server with that url and no authentication. Apps that only start
  local servers as a command use `npx -y mcp-remote http://127.0.0.1:47390/mcp`.

If the tools are there but every call fails, check these with the user:

- The render window is open.
- Agent access is allowed: the user can stop it with the badge in the corner of the render, and allow it there again.
- The url you use is the one that **Tools > Connect AI Agent...** in the render window shows. A second Rayscaper, for
  example the standalone app next to SketchUp, uses another port.

## How to work

1. **Look before you change.** Call `get_scene` first: it lists the camera, environment, post processing, render
   settings, materials and lights with their names. Call `get_selection` when the user says "this" or "the selected
   ...". Then look at the render with `get_render_image` and `wait_for_samples: 32`. `render_control` starts, pauses
   and resumes the render, and tells its state and samples.
2. **Find things in space with `pick_point`.** It tells what is at a point of the image (x and y from 0 to 1, from the
   top left): the material, the position in meters (Z is up), the normal and the bounds of the object. Use it to find
   the table to hang a light above, the floor height or the wall to aim at.
3. **Change one thing, then look again.** After a change call `get_render_image` with `wait_for_samples` (about 32
   for a quick look, 128 or more to judge noise and fine detail) and judge the image yourself: exposure, contrast,
   color, composition. Repeat until it looks right. Post processing doesn't restart the render, so its changes show at
   once; the environment, materials, lights and camera restart it.
4. **Keep the way back.** Every set tool returns the previous settings. Materials, the environment, scatters and post
   processing can't be undone by the user, so remember the previous values and offer to put them back.
   `set_material` with `restore` puts a material back as it was before your first change, image textures included.
   Lights placed or moved in SketchUp and SketchUp camera moves are steps the user can undo in SketchUp.
5. **Save what the user asked for** with `save_render` and an absolute path ending in `.png`, with
   `wait_for_samples` (256 to 1024 for a final image). `.exr` needs a Rayscaper license. A wait returns after about
   45 seconds, before agent apps give up on a tool call: when the result says `timed_out`, call again with the same
   `wait_for_samples` until the samples are in.
6. **Compare with the render history.** `render_history` with `save` keeps the live render (wait for a clean one
   first), `list` lists the saved renders and `show` shows one in the render window and returns it as an image.
   `set_post_processing` applies to a shown render too, to try another look without rendering again;
   `apply_post_processing` restores the look a render had when it was saved. A wait for samples shows the live render
   again. Use it to keep the versions you try, for example two skies or three lighting moods, and to show the user the
   best.
7. **Use the tools, not the UI.** Every change above has its own tool. `get_window_image` and `send_ui_input` show and
   click the application's UI itself: use them only when the user asks for something in the UI. A wrong click can
   open another scene and lose the user's work (the File menu of the standalone app loads a sample scene without
   asking), and a menu you open stays open in front of the user. Close what you open with Escape.

## Setting up a whole scene

A model straight from SketchUp renders with a sky, AI denoising and SketchUp's materials, and a model saved with
Rayscaper has its own settings: read `get_scene` before you change them. To set it up, work from the big picture to
the details and look at the render after every step:

1. **Sky and exposure** (`set_environment`, `set_post_processing` with `denoise`): the light decides everything else.
2. **Materials**: glass that is real glass, water that is water, and finishes from the asset library for the large
   surfaces (`find_materials`).
3. **Grass and scatters**: lawns that grow real grass, and plants and trees from the components of the model (see
   Craft).
4. **Lights**: lamps, fixtures and accents, mostly for evening and interior shots.
5. **Camera**: the view, focal length and the resolution of the image.
6. **Render settings and post processing**: samples for the final image, then the look (contrast, white balance,
   vignette, bloom).
7. **Final render** with `save_render`.

## Craft

- **Light:** the sky sets the mood. `set_environment` takes a sky preset (Clear, Hazy, Overcast, SoftLight,
  GoldenHour, Sunset, BlueHour) and the sun's elevation and rotation; a low sun gives long shadows and warm light, but
  nearby walls can block it, so check where it falls. For night, put the sun below the horizon or use a dark
  environment, and light the scene with lamps. `find_hdris` finds HDRIs in the asset library for real-world light.
- **Lamps:** turn a lamp shade into a light source by making its material emissive (warm white is about 2700 K), or
  `place_light` a point, spot or area light inside or below it. Give a light a `preset` (for example `Bulb 60 W`,
  `LED Downlight`, `Window`) to make it as bright as the real one instead of guessing an intensity, or set its
  `brightness` in lumen (cd/m² for an area light without normalize, lux for a directional light); it keeps when the
  temperature or a spot's cone changes. Real lamps need auto exposure at night. Spotlights take IES profiles for
  realistic beams. Warm interior light against a cool blue-hour sky is a classic evening look.
- **Changing lights:** `get_light` returns the settings of a light as `set_light` takes them, with its position and
  direction. `set_light` changes, moves, turns or resizes a light; `remove_light` removes it and returns its
  settings, so `place_light` can bring it back.
- **Exposure:** adjust it with `set_post_processing` before adding lights. Interiors lit only through windows usually
  need +1 to +2 EV. Avoid clipped windows and crushed shadows.
- **Camera:** `set_camera` moves and aims the camera and sets the focal length (24 to 35 mm for interiors), the
  resolution and depth of field. Keep verticals straight by keeping the camera level (target at the same height as
  the position) for architecture. In SketchUp it moves SketchUp's camera, and fails while Lock Camera is on. While a
  SketchUp section plane cuts the model, `get_scene` reports its `section_cut` under the camera, and
  `section_cut_light` sets whether daylight comes in through the cut (`LetIn`) or the room keeps its shadows
  (`KeepShadows`, for a cutaway of an interior).
- **Materials:** `get_material` and `set_material` change a material by name; colors are linear RGB from 0 to 1, so
  a mid grey is about 0.2, not 0.5. `find_materials` searches the asset library, and `set_material` with `asset`
  replaces a material with one from there. A change is Rayscaper's own, the SketchUp material stays as it is.
  Glass takes a `glass_preset` (`Clear`, `Window Pane`, `Lightly Frosted`, `Frosted`, `Crystal`, `Acrylic`, `Water`,
  `Diamond`, `Anti-Reflective`) that sets its IOR, roughness and `thin` and keeps the color: `Window Pane` for a window
  modelled as a single face, `Water` for water in a glass or a vase.
  Curtains, lampshades and leaves that are lit from behind need `translucency` (0.4 to 0.7 for sheers, or the
  `Sheer Fabric` finish), not a low opacity: translucency lets the light through softly, opacity makes a hole.
- **Grass:** `set_material` with `type: Grass` turns the material of a lawn into grass that grows on every face
  painted with it, in the render only. Start from a `grass_preset` (`Mowed Lawn`, `Garden Lawn`, `Meadow`,
  `Dry Grass`, `Artificial Turf`). The lawns and the meadow keep the color, a medium to dark green, about
  (0.06, 0.14, 0.035), looks natural; `Dry Grass` and `Artificial Turf` set a straw and a turf green. Then tune
  `grass_height` (meters), `density` (relative to the preset), `mowing_stripes` (meters, 0 is off), `dryness`,
  `patchiness`, `flattened`, `seed_heads`, `wind` and `wind_direction` (degrees, 0 is +X), `tip_color` and the others that `set_material` lists. `get_material`
  reports what grew in `grass_grown`: clumps, blades and `capped`, which says an object holds too much grass and
  grows it less densely. The grass grows again a second or two after a change, so render after it. A lawn of the Grass
  material looks better than a scatter of grass components; Rayscapers before the Grass material don't list `Grass`
  among the types of `set_material`, scatter grass there.
- **Fur:** `set_material` with `type: Fur` grows real strands on every face painted with the material, in the
  render only: shag and short pile rugs, sheepskin, faux fur throws, plush cushions, the coat of an animal. Start
  from a `fur_preset` (`Shag Rug`, `Short Pile Rug`, `Sheepskin`, `Faux Fur`, `Plush`, `Animal Fur`, `Long Hair`);
  they keep the color, except `Animal Fur` and `Long Hair`, which color the strands by `melanin` and
  `melanin_redness`. Then tune `fur_length`
  (meters), `fur_density` (strands per cm²), `strand_thickness` (mm), `curl`, `fur_direction`, `shine`, `clumping`,
  `comb_random` and `comb_direction` and the others that `set_material` lists. Give it the color the rug has; Rayscaper
  compensates for the light that bounces between the strands, a cream rug is about (0.55, 0.46, 0.33). An image texture in UV
  mapping colors every strand by the texture at its root, so a patterned rug keeps its pattern. `get_material`
  reports `fur_grown`: the strands and `capped`. Fur takes longer to render than a plain material; for velvet,
  felt or a fabric seen from afar, the `sheen` of PBR is enough.
- **Scatters:** `get_scatters` lists the surfaces (groups and components, with the materials of their faces) and the
  components that can be scattered, with their size. `set_scatter` spreads components over a surface, limited to the
  faces of `surface_materials`: the beds of a garden group get plants, its border shrubs. The plants to scatter often
  stand once in the model or on a hidden tag. Typical densities per m²: grass components 100 to 300, ground cover 5
  to 20, shrubs 0.5 to 2, trees 0.01 to 0.05. Mix several plants with weights, vary their scale (0.8 to 1.3), sink
  grass and shrubs a little with `offset` (-0.01 to -0.03 m), and start with a low density: many instances slow the
  render down. `remove_scatter` removes a scatter and returns its settings, so `set_scatter` can make it again.
- **Look:** tone mapping, contrast, white balance, vignette, bloom and glare are post processing, so try them freely.
- **Speed:** for quick comparisons lower the samples with `set_render_settings` and put them back afterwards.

## Ideas to offer

- Setting up a model from scratch for a client presentation: plants, materials, sky, lights, camera and look.
- Art direction: "make this look like a magazine shot", judged and improved step by step.
- The same view at several times of day, each saved as its own image.
- Evening lighting: find the lamps and place lights where a lighting designer would.
- Material options from a design brief, rendered side by side, then the original materials back.
- Troubleshooting: why a render is dark, noisy or flat, and the fix.
- Finding the best viewpoints of a model with quick low-sample renders.
