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. For what to type, see the Prompt Reference.
There are sixteen tools, and they share one vocabulary. A mockup is a look (device, background, flat or 3D), an animation, and its items (the screenshots or recordings in it). Every tool that takes a look takes the same arguments, and the tools that read a mockup return them under the same names, so anything an agent reads it can pass straight back. Every setting is optional.
| Tools | |
|---|---|
| Discover | list_devices, list_presets, list_projects, get_project, get_editor_configuration, get_credits |
| Render | preview_mockup, create_mockup, create_video_mockup |
| Projects | create_project, update_project, organize_projects, delete_project |
| The app on screen | open_in_editor, update_editor |
| Files | request_folder_access |
The look
Taken by create_mockup, create_video_mockup, preview_mockup, create_project, update_project and update_editor.
| Parameter | Type | Description |
|---|---|---|
device | string | e.g. iPhone 17 Pro (see the device list below) |
display | string | A folding phone, flat: inner, cover or cover_open. Left out, it is picked from the screenshot’s size |
bezel_color | string | e.g. Cosmic Orange, must be valid for the device |
background_type | string | none (transparent), solid, gradient or image |
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 |
gradient_start_angle / gradient_end_angle | number | Exact angles in radians, overriding gradient_direction. They are what get_editor_configuration returns, so an on-screen gradient can be reproduced exactly |
background_image | string | A picture’s file path, or a bundled background’s name. Implies image |
background_blur | number | 0–1, how much the background picture is blurred |
zoom_percent / zoom_position | number / string | Flat: 0–200 (default 100), anchored 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 | Turns an iPad or a folding phone’s display and flips the canvas. Left out, a flat device follows the screenshot’s shape |
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 |
shadow | object | The device’s shadow, flat or 3D: type (none, behind for a drop shadow, below for a shadow on the floor the device stands on, raking for a long shadow a low light throws across the background, apple for the Shadow tab’s Apple Look), opacity and softness (0–1), offset_x / offset_y (−1…1, which way it falls; positive offset_y is down). Any field without type turns it on; none turns it off and keeps the rest |
is_3d | boolean | A 3D model of the device instead of a flat bezel. Any of the next six turns it on |
camera | object | yaw, pitch (degrees), fill (percent of the frame’s height, default 85), lens (degrees), offset_x, offset_y |
lighting | object | rig (bank, tabletop, rails, arch, showroom), angle (degrees the lights are turned), exposure (stops), contrast |
orientation | string | 3D iPad or folding phone: automatic, portrait or landscape |
fold | number | A folding phone in 3D: 0 shut … 1 flat |
screen_blur | number | A folding phone in 3D: how strongly its screens blur while it is part open |
depth_of_field | object | 3D only: type (none, lens for a real lens, where what is as far away as the focus is sharp; radius for a sharp circle round the focus), focus_x / focus_y (−1…1, the spot on the device in focus; focus_y 1 is its top edge, focus_x 1 its right side), focus_size (radius only, 0–1) and blur (0–1). The blur grows with the device in the frame: about 0.2 looks like a real camera at the default framing, and a close-up needs far less |
preset | string | Start from a saved preset |
like_project (+ like_folder) | string | Start from a project’s look and animation, as a template. The project is left untouched |
like_editor | boolean | Start from what is open in the editor |
Angles are degrees and fill is how much of the frame the device takes, the same numbers the app’s own camera controls show. Positive yaw moves the camera to the right, so the device looks turned to the left. A low lens is a long lens (flat, like a product shot); a high one exaggerates perspective. The rails lighting setup is the one the app calls Bars, and tabletop is the default.
3D needs a device that has a 3D model, in a color that model is made in. Asked for anything else, a tool refuses and says what is available: the nearest device with a model, or that model’s colors. Nothing is substituted quietly.
An agent can’t open your files, so what follows from a picture’s shape is decided for it: a landscape screenshot turns a flat iPad on its side, a folding phone’s screenshot goes on the display it is the size of, and a folding phone in 3D given one picture is shown open or shut to match it. The result says what was decided, and warns when a picture isn’t the shape of the device’s screen.
The animation
Taken by create_video_mockup, preview_mockup, create_project, update_project and update_editor.
| Parameter | Type | Description |
|---|---|---|
movements | object[] | 3D camera movements, in order. Each is a named one (preset, with optional start_time or delay, and duration) or one described by its poses |
keyframes | object[] | A flat mockup’s zoom push-ins: start_time, duration, zoom_percent (100–300), interpolation (smooth, flow, gentle, snappy), anchor {x, y} (0–1, y = 0 is the top of the screen) |
trim | object | Keep part of a recording: {start, end} in seconds |
lead_in | number | Seconds of intro before a recording starts playing, while a movement brings the device in |
duration | number | How long a still’s video is. Left out, it ends with its last movement |
Named movements
| Movement | Seconds | Movement | Seconds | |
|---|---|---|---|---|
| Sweep | 3.9 | Turn In | 2.0 | |
| Zoom | 3.3 | Showcase | 6.2 | |
| Flat Drift | 4.7 | Stand Up | 1.7 | |
| Settle | 2.7 | Profile | 5.0 | |
| Rise | 2.1 | Swing In | 5.0 | |
| Tumble | 5.0 | Flip Side | 2.0 | |
| High Orbit | 3.2 |
The iPhone Duo also has Opening and Closing (2 s each), and Landscape, Portrait, Seated, Standing and Durability (1.4 s each), which open, close and pose it. Each movement plays at the pace it was designed at unless a duration says otherwise.
Movements described by poses
A movement of your own is two or more poses. A pose is a time plus whichever of these change. What it leaves out stays at the mockup’s own framing.
| Pose field | Description |
|---|---|
yaw, pitch, fill, lens, offset_x, offset_y | The camera’s fields, as in camera. Raising fill between two poses pushes in (85 → 170 doubles the device). To push in on the top of the screen, raise fill and lower offset_y |
roll | Degrees the device is rotated in the frame, clockwise |
light | Degrees the lights are turned, as lighting.angle |
fold, screen_wipe | A folding phone: how far open (0 shut … 1 flat), and whether its screens show (1) or are blanked (0) as they wipe while it folds |
focus_x, focus_y, focus_size, blur | The focus, as in depth_of_field. Two poses that differ in them pull the focus. They need a depth_of_field with a type |
ease | How the camera leaves this pose for the next: flow (default), smooth, gentle, snappy, {"bezier": [x1, y1, x2, y2]} or {"spring": bounce} |
This is what makes a described animation possible. Asked for “a slow reveal from behind that ends straight on”, an agent writes the poses for it, looks at them on a contact sheet, and adjusts before it exports. The Prompt Reference has examples with the poses each one produced.
Rules
The same ones the app’s timeline has:
keyframeszoom a flat mockup and are refused in 3D, where a push-in is a movement.- A folding phone’s animations are refused on a phone that doesn’t fold.
- Movements can’t overlap, and one that starts after a recording ends is refused with the recording’s real length.
- Two movements back to back are a cut. When one starts the instant the last one ends, with a different first pose, the picture cuts from one to the other. That is how a montage of separate shots is made. Leave a gap between them and the camera glides across it instead.
- An intro has to have something moving in it. Empty time in front of the first movement is taken out.
Discover
list_devices returns every device with its bezel colors, whether it has a 3D model and in which colors, whether it folds and which displays it has. It also lists the lighting setups, the camera movements with their lengths, the folding phone’s animations, the bundled backgrounds, and the accepted values for everything else.
list_presets returns the presets you’ve saved in the editor.
list_projects returns your projects and the folders they are in (optionally one folder), and which one is open in the editor.
get_project returns one project’s look, animation and items, without opening it.
get_editor_configuration returns the same for what is in the editor right now, plus which project it is and whether the editor or the projects list is showing.
get_credits says whether you are on an unlimited plan (unlimited), how many credits you hold (credits), and what one export costs you right now (image_cost, video_cost, both 0 on an unlimited plan).
Render
preview_mockup
Takes the look, the animation and a source, and returns the mockup as a small picture the agent can see (up to 480 px). No file is saved and no credit is spent. time picks a moment of an animation. This is how an agent checks its own framing before exporting.
To look over a whole animation in one call, pass times (a list of moments, e.g. [0, 2, 4, 5.5]) or frames (that many, spread evenly from the first frame to the last) instead of time. The moments come back as one picture, a contact sheet: a grid of small frames in order, each labelled with its time, up to 24 on a sheet. A recording’s own picture doesn’t advance from frame to frame (it is shown by its first frame). What a sheet shows moving is the device and the camera.
create_mockup
Renders one or more screenshots to PNG files. Takes the look, plus:
| Parameter | Type | Description |
|---|---|---|
source | string | Absolute path to a screenshot (PNG, JPEG, or HEIC) |
sources | string[] | A batch, max 10 per call, identical settings for all |
other_screen | string | A folding phone in 3D: the picture for its other display |
scale | integer | 1, 2, or 3: multiplier of the 1080×1920 base canvas (default 2) |
output_path | string | A directory, 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 picture of the first result |
Each image costs 1 Screeny credit unless you have an unlimited plan.
create_video_mockup
Renders a screen recording (MP4, MOV, or M4V) playing on the device, or a still screenshot brought to life by an animation. Takes the look, the animation, source, other_screen, output_path, and:
| Parameter | Type | Description |
|---|---|---|
muted | boolean | Strip the recording’s audio (default true) |
quality | string | standard = 10 Mbps (default), high = 20 Mbps |
frame_rate | integer | 60 (default) or 30 |
Output is MP4, or MOV with an alpha channel when background_type is none, ready to composite in a video editor. Each video costs 3 Screeny credits unless you have an unlimited plan.
With like_editor or like_project and no source, both render tools export that mockup as it is: “export what I have open”.
Note: Long videos take a while to export, and the Screeny app must stay in the foreground until the export finishes. Screeny renders one thing at a time: a call made while another render is running is told to try again.
Projects
None of these render anything or cost credits.
create_project makes a new project: a name, optionally a folder (made if it doesn’t exist), items ([{source, other_screen}], up to 10), a look and an animation. With no items it is a look saved on its own, a house style. A name already used in that folder is refused, not numbered.
update_project changes a project’s look or animation (only what is passed changes) and its items: items replaces them, while add_items, remove_items and item_order change them. If the project is open in the editor, the change is made there, so the screen and the file agree.
organize_projects takes one action per call: rename, duplicate, move (to a folder, made if needed), create_folder, rename_folder, export (a copy of the project file into a granted folder, to send to someone) and import (a .screeny file into your projects).
delete_project deletes a project, or a folder with every project in it. Permanent: there is no Recently Deleted. It needs both the name and the folder, so nothing is deleted on a guess, and it is marked as destructive so clients that confirm such tools will ask you first.
The app on screen
open_in_editor brings Screeny to the foreground showing a project, the Quick Mockup, or the projects list.
update_editor changes what is open, live, with the same arguments as update_project. You watch it happen. save_as turns the Quick Mockup into a named project.
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. Color names are forgiving: Cosmic Orange and CosmicOrange both work. The 3D column says which colors the device’s 3D model is made in; a dash means it has no 3D model.
| Device | Bezel colors | 3D |
|---|---|---|
| iPhone 11 / 12 / 12 mini | White | — |
| iPhone 11 Pro / Pro Max, 12 Pro / Pro Max | Silver | — |
| iPhone 13 / 13 mini | Midnight, Starlight | — |
| iPhone 13 Pro / Pro Max | Graphite, Silver | — |
| iPhone 14 / 14 Plus | Blue, Midnight, Purple, Red, Starlight | — |
| iPhone 14 Pro / Pro Max | Deep Purple, Gold, Silver, Space Black | — |
| iPhone 15 / 15 Plus | Black, Blue, Green, Pink, Yellow | — |
| iPhone 15 Pro / Pro Max | Black Titanium, Blue Titanium, Natural Titanium, White Titanium | — |
| iPhone 16 | Black, Pink, Teal, Ultramarine, White | Black |
| iPhone 16 Plus | Black, Pink, Teal, Ultramarine, White | — |
| iPhone 16 Pro / Pro Max | Black Titanium, Desert Titanium, Natural Titanium, White Titanium | all |
| iPhone 17 | Black, Lavender, Mist Blue, Sage, White | all |
| iPhone 17 Pro / Pro Max | Cosmic Orange, Deep Blue, Silver | all |
| iPhone Air | Cloud White, Light Gold, Sky Blue, Space Black | all |
| iPhone 18 Pro / Pro Max | Black, Burgundy, Glacier, Silver | all |
| iPhone Duo (folds) | Night Sky, Star White | all |
| iPad (A16) | Blue, Pink, Silver, Yellow | all |
| iPad mini (A17 Pro) | Blue, Purple, Space Gray, Starlight | all |
| iPad Air 11″ (M4) | Blue, Purple, Space Gray, Starlight | Purple |
| iPad Air 13″ (M4) | Blue, Purple, Space Gray, Starlight | all |
| iPad Pro 11″ (M5) | Silver, Space Black | — |
| iPad Pro 13″ (M5) | Silver, Space Black | all |
| MacBook Neo | Blush, Citrus, Indigo, Silver | all |
| MacBook Air 13″ / 15″ (M5) | Midnight, Silver, Sky Blue, Starlight | all |
| MacBook Pro 14″ / 16″ (M5) | Silver, Space Black | Silver |
| iMac 24″ (M4) | Blue, Green, Orange, Pink, Purple, Silver, Yellow | all |
| Studio Display / Studio Display XDR | On Light, On Dark | — |
The iPhone Duo is one device with three displays when flat: inner (the unfolded panel), cover (the outside screen, phone shut) and cover_open (the outside screen with the phone spread open). In 3D it is one phone that shows a picture on each display and opens and closes. The inner display takes a 2007 × 2853 screenshot and the cover a 1398 × 2034 one, and cover_open is drawn in landscape only. clean_status_bar has no effect on the Duo: its mockups keep the status bar the screenshot was captured with.
The Studio Display has one finish. Its two “colors” are the same aluminium body drawn for a light or a dark background. Macs are landscape only.
list_devices is the live version of this table. This one is a snapshot.
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. Those are the same defaults as a fresh editor.
Where files are saved
Tell your agent where you want the result, like “save it next to the screenshot” or “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, …).
Projects are not files you choose a place for: they live with your other Screeny projects (in iCloud Drive’s Screeny folder when iCloud is on) and show up in the app’s projects list.
Credits
Exports made through MCP use the same Screeny credits as exports made in the app: 1 credit per image, 3 per video. Users on an unlimited plan aren’t charged. Credits are only deducted after a successful render, so failed exports never cost anything. If the balance is too low, the tool call fails with a clear message and nothing is charged. Previews, and everything that creates or changes a project, are free.
Ask your agent “how many credits do I have left?” or “will my plan cover 40 videos?” and it reads your plan and balance with get_credits. Credits and plans are bought in the Screeny app; no tool spends money.
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. - The Claude plugin finds the port itself, so there is no URL to update there.
”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.
”Screeny is already rendering”
Screeny renders one thing at a time, and an export of your own from the app’s window counts. The agent tries again once it is done.
Claude doesn’t see the server
The Claude app can’t connect to Screeny by URL, so adding the address to a config file does nothing. Add the Screeny plugin from Settings → Connectors → Discover instead, as described in Connect your client.
Claude lists only screeny_status
That is the Screeny plugin telling you it can’t reach the app. Open Screeny and check that MCP Server is on in Settings → Automation. The other tools appear a few seconds later. If they don’t, ask Claude to check Screeny’s status, or restart Claude.
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 Screeny projects are different: they are the app’s own documents, and an agent can create, change, rename and delete them. Deleting is permanent and is a separate tool, marked destructive, so an AI client that asks before destructive actions will ask before that one.
The Claude plugin puts one small program between Claude and the app, and its source is public . It talks only to Screeny at 127.0.0.1, makes no other network request, and reads and writes no files.
Your screenshots and recordings never leave your machine: all rendering happens locally inside the app.