gambaran-mcp

Device mockups for AI agents. Frames a screenshot in a photorealistic phone, tablet or laptop on a styled backdrop, and writes a PNG — from Claude Code, Claude Desktop, or any other MCP client.

Same renderer as the Gambaran app, so what an agent produces matches what the app produces.

Install

claude mcp add gambaran -- npx -y gambaran-mcp

Nothing is hosted. The server runs as a local process the client starts and stops, and your screenshots never leave the machine.

Use

Frame login.png in an iPhone 17 Pro on a dark gradient, 9:19.5.

Take every screenshot in ./shots and produce the App Store sizes.

Tools

| Tool | What it does | |---|---| | create_mockup | One mockup. Returns the file path plus a small preview. | | batch_mockups | One screenshot across many device/ratio/layout combinations. | | list_devices | Device ids, names, categories, screen aspect. | | list_layouts | Which layouts each device category offers. | | create_video_mockup | Animates a still into an H.264 MP4, for store previews. | | list_ratios | Named sizes by platform — App Store, Instagram, YouTube. |

Resources: gambaran://devices, gambaran://presets/backdrops. Prompt: app-store-screenshots walks a folder through a full store set.

create_mockup

| Field | Notes | |---|---| | screenshot | File path, data: URI, base64, or http(s) URL. Omit for an empty device. | | device | Default iphone-17-pro. | | layout | Default single. Multi-device and tilted layouts are not offered for every category. | | ratio | "W:H", between 1:5 and 5:1. Default 9:16. | | backdrop_preset / backdrop_color / backdrop_gradient / backdrop_image | Most specific wins. | | backdrop_angle, texture | Gradient angle in degrees; grain, grid or dots. | | tint | Device body colour. | | slots | Extra screenshots for multi-device layouts, keyed "2" and "3". | | output | Defaults to the working directory. |

Output is capped at a 2400px long edge, and oversized inputs are downscaled to match — a 48MP photo is a lot of pixels for a screen cutout that is never drawn larger than that.

create_video_mockup

Takes everything create_mockup takes, plus motion (nine named templates — zoom-in, pop-in, float, and so on, matching the app's), duration_ms and fps. Output is 1080px on the long edge, H.264/yuv420p with +faststart so a store page can start playing before the file has finished downloading.

The source must be a still image. Animating an existing video would mean decoding one in Node; the on-device exporter gets that from AVFoundation and there is no equivalent here.

ffmpeg ships with the package via ffmpeg-static, so there is nothing to install. Renders run about 8 frames a second, so a 5-second clip takes roughly 20 seconds — progress notifications are sent when the client asks for them.

Why the preview is small

A 2400px PNG is roughly half a megabyte, which is ~700KB of base64 — too much to put in a model's context on every call. The full-resolution file goes to disk and a 384px thumbnail comes back inline, so the agent can see what it made without the result crowding out the conversation.

Development

npm run build      # bundle to dist/
npm run start      # build, then run the server on stdio
npm run render -- --screenshot shot.png --device iphone-17-pro
npm run fixtures -- ./out shot.png    # render the parity fixture matrix
npm run parity -- ./baseline ./out    # diff two fixture directories

scripts/compare.mjs defaults to a 0.05% threshold, which is right for Node-against-Node: CanvasKit is bit-for-bit deterministic, so any movement is a change somebody made. Comparing against the app's own export is the looser case — pass PARITY_THRESHOLD=1.5, and only there.