MCP Tools Reference
Full reference for the tools Screeny’s MCP server exposes. You don’t call these yourself — your AI client discovers them automatically and picks the right one for your request.
list_devices
Lists every device Screeny can render, each with its valid bezel colors (colors are device-specific — e.g. iPhone 17 Pro only comes in Cosmic Orange, Deep Blue, and Silver), plus the accepted values for aspect ratios, zoom positions, status bar themes, and gradient directions. Agents call this first when they’re unsure which values are valid.
list_presets
Lists the presets you’ve saved in Screeny’s editor (named mockup configurations: device, background, zoom, aspect ratio, status bar). An agent can apply a preset by passing its name to create_mockup or create_video_mockup. Presets don’t store source media or keyframe animations.
get_editor_configuration
Returns the mockup settings currently active in the Screeny editor on screen. This powers “make more like what I have open” requests — the returned keys use the same names as create_mockup’s arguments, so the agent can pass them straight back in.
create_mockup
Renders one or more screenshots into device mockups and saves them as PNG files. The screenshot is provided as an absolute file path (source) or several paths (sources — up to 10 per call, identical settings for all).
Every setting is optional. Omitted settings fall back to the preset (if one is given) or to Screeny’s defaults; any explicit setting overrides the preset.
| Parameter | Type | Description |
|---|---|---|
source | string | Absolute file path to a screenshot (PNG, JPEG, or HEIC) |
sources | string[] | Batch of file paths, max 10 — identical settings for all |
preset | string | Name of a saved preset to start from |
device | string | Device to render, e.g. iPhone 17 Pro (see the device list below) |
bezel_color | string | e.g. Cosmic Orange — must be valid for the chosen device |
background_type | string | none (transparent), solid, or gradient |
background_color | string | #RRGGBB hex — implies solid |
background_intensity | number | 0–1: 0 = white, 0.5 = the color as given (default), 1 = fully saturated |
gradient_start / gradient_end | string | #RRGGBB hex — imply gradient |
gradient_direction | string | horizontal, vertical, diagonalDown, or diagonalUp |
zoom_percent | number | 0–200, default 100 |
zoom_position | string | top, center, or bottom |
aspect_ratio | string | Fit, 1:1, 9:16, 4:5, 5:7, 3:4, 3:5, or 2:3 |
landscape | boolean | Flips the aspect ratio (default false) |
clean_status_bar | boolean | Replace the screenshot’s status bar with a clean 9:41 / full-signal / full-battery one (default true) |
status_bar_theme | string | auto (default — picks based on the screenshot’s brightness), black, or white |
scale | integer | 1, 2, or 3 — export resolution multiplier of the 1080×1920 base canvas (default 2) |
output_path | string | Directory to save into, or an exact file path (single source only) — any granted folder works; existing files are never overwritten |
return_preview | boolean | Also return a small inline preview of the first result (default false) |
Returns the saved PNG path(s). Each image costs 1 Screeny credit unless you have an unlimited plan.
create_video_mockup
Renders a screen recording (MP4, MOV, or M4V) into a device mockup video — or animates a still screenshot into a video clip using keyframe zoom effects. It accepts all of create_mockup’s settings, plus:
| Parameter | Type | Description |
|---|---|---|
source | string | Required. Path to a video — or to a screenshot, which becomes a still clip animated by keyframes |
keyframes | object[] | Animated camera push-ins on the device (see below) |
duration | number | Clip length in seconds when the source is a still image (default 10, auto-extended to fit the keyframes) |
muted | boolean | Strip the source video’s audio (default true) |
quality | string | standard = 30 fps / 10 Mbps (default), high = 60 fps / 20 Mbps |
frame_rate | integer | 30 or 60 — overrides the frame rate implied by quality |
Each keyframe is a camera push-in: zoom ramps in over ~0.75 s, holds, and ramps out. Keyframes must not overlap, and the zoom multiplies the base zoom_percent (100 = no extra zoom, 200 = 2× push-in):
| Keyframe field | Type | Description |
|---|---|---|
start_time | number | Required. Seconds from the start of the clip |
duration | number | Required. Seconds, minimum 0.25 |
zoom_percent | number | 100–300, default 200 |
interpolation | string | easeInOut (default), linear, easeIn, or easeOut |
anchor | object | {x, y}, each 0–1 — where to zoom toward; default (0.5, 0.5) is center, y = 0 is the top |
Output is MP4 — or MOV with an alpha channel when background_type is none, ready to composite in a video editor. Videos render at the source’s native resolution. Each video costs 3 Screeny credits unless you have an unlimited plan.
Note: Long videos take a while to export, and the Screeny app must stay in the foreground until the export finishes.
request_folder_access
Asks you to grant Screeny persistent access to a folder — reading files and saving new ones — via the native macOS folder panel (see Folder access in the how-to guide). The panel opens pre-navigated to the requested folder with a Grant Access button — nothing is granted unless you click it, and you can pick a different folder or cancel. Mac only.
Devices and colors
Every device Screeny supports over MCP, with its valid bezel colors. Color names are forgiving — Cosmic Orange and CosmicOrange both work.
| Device | Bezel colors |
|---|---|
| iPhone 15 / 15 Plus | Black, Blue, Green, Pink, Yellow |
| iPhone 15 Pro / 15 Pro Max | Black Titanium, Blue Titanium, Natural Titanium, White Titanium |
| iPhone 16 / 16 Plus | Black, Pink, Teal, Ultramarine, White |
| iPhone 16 Pro / 16 Pro Max | Black Titanium, Desert Titanium, Natural Titanium, White Titanium |
| iPhone 17 | Black, Lavender, Mist Blue, Sage, White |
| iPhone 17 Pro / 17 Pro Max | Cosmic Orange, Deep Blue, Silver |
| iPhone Air | Cloud White, Light Gold, Sky Blue, Space Black |
| iPad (A16) | Blue, Pink, Silver, Yellow |
| iPad mini (A17 Pro) | Blue, Purple, Space Gray, Starlight |
| iPad Air 11″ / 13″ (M4) | Blue, Purple, Space Gray, Starlight |
| iPad Pro 11″ / 13″ (M5) | Silver, Space Black |
When no settings are given at all, Screeny renders an iPhone 17 Pro in Cosmic Orange on a soft solid background, portrait, with a clean status bar — the same defaults as a fresh editor.
Where files are saved
Tell your agent where you want the result — “save it next to the screenshot”, “put it on my Desktop” — and it will pass output_path accordingly. Saving follows the same rules as reading: the destination must be inside a folder you’ve granted, and agents can request access to a new one the same way.
When no destination is given, results go to Screeny’s own MCP Exports folder, inside the app’s container:
~/Library/Containers/lazare.kolebka.screeny/Data/Documents/MCP Exports/One hard guarantee either way: Screeny never overwrites existing files. An exact output_path that already exists is refused, and auto-generated names get a collision counter — exports only ever create new files.
Files are named:
Screeny-Mockup-<source-name>-<timestamp>.pngBatch renders append an index (-01, -02, …).
Troubleshooting
My AI client can’t connect
- Make sure Screeny is running and the MCP Server toggle in Settings → Automation is on — the server only runs while the app does.
- Check the URL. The green status row in Settings shows the exact address; if port 9410 was taken by another app, Screeny may be on 9411–9419. Tap the row to copy the current URL and update your client config.
- The endpoint path is
/mcp—http://127.0.0.1:9410alone won’t work.
”File not found (or its folder isn’t readable)”
This is the sandbox doing its job: the file lives in a folder you haven’t granted to Screeny. Your agent will usually resolve this itself by calling request_folder_access — just click Grant Access in the panel that appears. You can also grant the folder ahead of time in Settings → Automation → Folder Access.
Video export fails partway through
Video exports can’t run in the background. Keep the Screeny app in the foreground.
Claude Desktop doesn’t see the server
Claude Desktop can’t connect to plain-HTTP localhost servers yet. Use Claude Code, Cursor, VS Code, or Codex instead.
Security
The MCP server is local-only: it binds strictly to 127.0.0.1 and cannot be reached from your network or the internet. It runs only while Screeny is open, and stops the moment you flip the toggle off.
File access is governed by the macOS sandbox. Screeny — and therefore any AI agent talking to it — can only touch folders you have explicitly granted through the native macOS folder panel, plus its own container. Within a granted folder it can read files and create new ones, but it never overwrites, modifies, or deletes anything. Agents can ask for access, but the grant always happens through an OS-mediated panel that only you can approve. Every grant is listed in Settings → Automation → Folder Access and can be revoked at any moment.
Your screenshots and recordings never leave your machine: all rendering happens locally inside the app.