MCP tool reference

Tool names are a stable contract: they are never renamed, only added. All tools return JSON; errors are { "error": "<code>", "hint": "…" } (error codes).

list_targets

List what ShowTake can film: Xcode projects/workspaces and their schemes under `path` (default: the working directory), iOS simulator devices, running Mac apps, and the current session.

Parameter	Type	Description
path	string	Folder to search for Xcode projects (default: working directory).

prepare_ios

Build the iOS app (Release), clone a clean simulator from ShowTake's golden device (status bar 9:41, en-US), install, launch and return the first screen plus a session_id. Takes 1-5 min.

Parameter	Type	Description
app_path	string	Prebuilt simulator .app to install instead of building.
appearance	string	light or dark (default light).
configuration	string	Build configuration (default Release: no debug overlays).
device	string	Simulator device type (default "iPhone 17 Pro").
env	object	Environment variables for the app.
launch_args	array	Extra launch arguments, e.g. demo-mode flags.
locale	string	App locale, e.g. en_US or de_DE (default en_US).
location	array	Simulated location [latitude, longitude].
os	string	iOS runtime version, e.g. "27.0" (default: newest installed).
photos	array	Image/video files to add to the Photos library.
privacy	array	Permissions to pre-grant: photos, camera, location, contacts...
project	string	Path to the .xcodeproj or .xcworkspace (relative to the working dir).
project_name	string	Library project to file takes under (default: scheme name).
scheme	string	Scheme to build.
status_bar	string	Status bar time (default "9:41").

prepare_macos

Launch a Mac app, size its window (16:9 by default, for Mac App Previews), check the Accessibility and Screen Recording permissions (returns guidance if missing) and return the first screen plus a session_id and `notes` (desktop clutter, notifications, window size) to relay to the user.

Parameter	Type	Description
app_path	string	Path to the .app bundle or the app's executable.
bundle_id	string	Bundle identifier of an installed app (instead of app_path).
env	object	Environment variables for the app (executables only).
keep_window_size	boolean	Keep the app's own window size instead of the 16:9 default.
launch_args	array	Extra launch arguments, e.g. demo-mode flags.
locale	string	App locale, e.g. en_US or de_DE (default: the Mac's).
project_name	string	Library project to file takes under (default: app name).
window_size	array	Window size [width, height] in points (default: the largest 16:9 window up to 1600x900 that fits the screen).

launch_app

(Re)launch the prepared app and return its first screen once it is ready for input. fresh=true resets its data first (iOS: reinstall); use it before every take.

Parameter	Type	Description
fresh	boolean	Reset app data first (default false).
session_id	string	Session from prepare_ios / prepare_macos (default: the current one).

observe

Wait until the UI is still and return the screen: screen_id, title, alert/keyboard flags and a compact element list `[index] Role "label" id=... value=... @x,y,w,h`.

Parameter	Type	Description
depth	integer	Accessibility tree depth limit (default 40).
session_id	string	Session from prepare_ios / prepare_macos (default: the current one).

screenshot

PNG of the app (simulator screen or window), downscaled. Fallback only: the element list is usually enough. With `take_id`: App Store screenshots and launch images from the take's key frames (the settled end of each step, or `at_ms`), exact store pixels, sRGB, no alpha, each file validated. One `preset`, a `presets` list, or a `bundle`: app_store = the App Store set for the take's platform (iPhone 6.3" 1206x2622, Apple's required class, + 6.9" 1320x2868; iPad 13" 2064x2752; Mac 2880x1800; `all_sizes` adds every other accepted size incl. iPhone Duo), launch = Product Hunt gallery 1270x760 + thumbnail 240x240, BetaList 1600x1200, Open Graph 1200x630, X 1600x900, LinkedIn 1200x627, square 1080x1080. Pro.

Parameter	Type	Description
all_sizes	boolean	With bundle app_store: every accepted App Store size, not only the required ones.
at_ms	array	Raw take times to capture (default: the end of every step).
background	string	Background of composed images (default: the render style's).
bundle	string	app_store: required App Store screenshot sizes for the take's platform; launch: launch-site and social images.
format	string	png (default) or jpeg; images over a platform's size limit are written as JPEG.
headline	string	Headline on launch/social images (default: the take title).
headlines	array	Marketing headlines, one per shot (default: each step's caption).
icon	string	App icon image for producthunt_thumbnail (default: the prepared app's icon).
out_dir	string	Destination folder (default: the take's exports/screenshots).
preset	string	One still preset.
presets	array	Several still presets.
session_id	string	Session from prepare_ios / prepare_macos (default: the current one).
style	string	App Store screenshots: raw (the real screen, full-bleed; default) or marketing (background + headline + generic device frame; Apple allows this for screenshots, never for App Previews). Launch and social images are always composed.
take_id	string	Take to extract stills from (instead of the live app).

doctor

Check that this Mac can film: macOS, Xcode (selected, license accepted, first-launch done), iOS simulator runtimes and device types, disk space, ShowTake's built-in AXe, Accessibility and Screen Recording, displays, the ShowTake app and MCP versions, the license and the connection to showtake.app. Returns a checklist; every failed check carries an error with ordered `fix` steps (exact commands or tool calls) and, when a human must act, `needs_user` + `tell_user`. Call it first on a new Mac and whenever a tool error is unclear. Takes a few seconds.

Parameter	Type	Description
platform	string	What you are about to film (default all).
project	string	Optional .xcodeproj/.xcworkspace to check (path, schemes, CocoaPods).
scheme	string	Optional scheme to look for in `project`.

license_status

The license plan, seats and update entitlement of this ShowTake install.

No parameters.

update_status

ShowTake's version and auto-update state: app and MCP server versions, whether a newer version is downloading or waiting to install, and what blocks it. ShowTake updates itself: it installs when no take, export or tool call is running, relaunches, and this MCP server switches to the new version on its own. check=true checks now; install=true installs a downloaded update now (never during a demo: the prepared session ends).

Parameter	Type	Description
check	boolean	Check for a new version now (waits up to 30 s for the answer).
install	boolean	Install an already downloaded update now and relaunch ShowTake.

upgrade

Buy Pro for this Mac: returns a checkout_url (bound to this Mac) and the price to give the user. After payment ShowTake activates itself, no key to paste; license_status shows pending_checkout until then. Returns already_pro when there is nothing to buy.

Parameter	Type	Description
plan required	string	Plan to buy.
seats	integer	Team seats (team_yearly only, 3-50, default 3; 2 Macs per seat).

tap

Tap an element (id / label / value / index) or a point (x, y) with a finger-like touch (macOS: accessibility press, click as fallback). Waits for the UI to settle and returns the new screen.

Parameter	Type	Description
caption	string	Viewer-facing caption for this step (<= 8 words). Required while recording.
id	string	Accessibility identifier (preferred).
index	integer	Element number from the screen `screen_id` (requires screen_id).
label	string	Accessibility label: exact, else case-insensitive contains.
nth	integer	0-based pick among several matches.
role	string	Role from the screen list (Button, TextField, Cell, CheckBox...) to narrow matches.
screen_id	string	The screen `index` refers to; an older screen is rejected (stale_index).
value	string	Element value, e.g. the placeholder of an unlabeled text field.
x	number	Point x (with y) when no element fits.
y	number	Point y.
zoom	string	Camera for this step: auto (default, the planner decides), on (always frame this step's element), off (keep the full view).

type_text

Type text at a human pace into the focused field (or tap `target` first), then verify the field shows it (ok=false when keystrokes were lost). Returns the new screen.

Parameter	Type	Description
caption	string	Viewer-facing caption for this step (<= 8 words). Required while recording.
mask	boolean	Mask the text in renders and logs (passwords).
submit	boolean	Press Return afterwards.
target	object
text required	string	Text to type (US keyboard characters).
zoom	string	Camera for this step: auto (default, the planner decides), on (always frame this step's element), off (keep the full view).

swipe

One-finger swipe: `direction` (finger movement) across `target` or the screen centre, or explicit from/to points. E.g. swipe left on a row to reveal its actions. Returns the new screen.

Parameter	Type	Description
caption	string	Viewer-facing caption for this step (<= 8 words). Required while recording.
direction	string	Finger movement.
duration_ms	integer	Gesture duration (default 300).
from	array	Start point [x, y].
target	object
to	array	End point [x, y].
zoom	string	Camera for this step: auto (default, the planner decides), on (always frame this step's element), off (keep the full view).

scroll

Scroll the content: direction=down reveals content further down. `amount` is the fraction of the screen (default 0.5). Returns the new screen.

Parameter	Type	Description
amount	number	Fraction of the screen, 0.1-0.8 (default 0.5).
caption	string	Viewer-facing caption for this step (<= 8 words). Required while recording.
direction required	string	Content direction.

press

Press a key or button: return, backspace, escape, tab, space, home (iOS), dismiss_keyboard, or a macOS shortcut like cmd+n. Returns the new screen.

Parameter	Type	Description
caption	string	Viewer-facing caption for this step (<= 8 words). Required while recording.
key required	string	Key name or shortcut.

wait_for

Wait until an element is present (gone=true: absent), or with no selector until the UI is still for stable_ms. Fails with `timeout` after timeout_ms. Returns the screen.

Parameter	Type	Description
gone	boolean	Wait until the element is absent.
id	string	Accessibility identifier (preferred).
index	integer	Element number from the screen `screen_id` (requires screen_id).
label	string	Accessibility label: exact, else case-insensitive contains.
nth	integer	0-based pick among several matches.
role	string	Role from the screen list (Button, TextField, Cell, CheckBox...) to narrow matches.
screen_id	string	The screen `index` refers to; an older screen is rejected (stale_index).
stable_ms	integer	Stillness required (default 400).
timeout_ms	integer	Hard limit (default 10000, max 60000).
value	string	Element value, e.g. the placeholder of an unlabeled text field.

mark

Add a caption (and optional zoom rectangle) at the current moment of the take, without an action.

Parameter	Type	Description
caption required	string	Caption text (<= 8 words).
emphasis	string	How strongly to zoom.
rect	array	Area to emphasise [x, y, width, height] in points.

start_take

Start recording the app (simulator screen or window) and the step/event log. Launch the app (fresh) first. Returns the take_id.

Parameter	Type	Description
preset_hint	string	Intended output, e.g. app_preview, x_16x9, tiktok_9x16.
session_id	string	Session from prepare_ios / prepare_macos (default: the current one).
title required	string	What the demo shows, e.g. "Add and finish todos".

end_take

Stop recording; writes raw.mov, events.json and flow.yaml, and judges the take: `clean` plus `issues` (too few steps, too short, keyboard left open, no-op or failed steps) and `rendered_estimate_s`.

Parameter	Type	Description
session_id	string	Session from prepare_ios / prepare_macos (default: the current one).

save_flow

Save a take's steps as a named, replayable flow (flows/<name>.yaml in the project), optionally with caption translations that localized replays (replay_flow with locales) film instead.

Parameter	Type	Description
caption_translations	object	Captions in other languages for localized replays: locale or language → one caption per captioned step, in the order save_flow returns them in `captions`, e.g. {"de": ["Neues Element", …], "ja": [...]}.
name required	string	Flow name, e.g. add-todos.
take_id required	string	Take to save.

replay_flow

Re-shoot a saved flow without an agent: prepares the target, launches fresh, runs every step with deterministic waits and records a new take. Returns its take_id and how it matched. With several locales or devices (Pro) it shoots one take per combination and returns them all in `takes`.

Parameter	Type	Description
devices	array	Device types to shoot (more than one needs Pro).
locales	array	Locales to shoot, e.g. ["en_US", "de_DE", "ja_JP"] (more than one needs Pro).
name	string	Flow name from save_flow.
path	string	A flow .yaml file to replay instead of a saved flow name.
project	string	Library project of the flow (default: search all).

retake

Replay the steps of an existing take as a new take (same target and environment), with no agent.

Parameter	Type	Description
take_id required	string	Take to re-shoot.

render

Plan the finished video of a take and save it as render.json: smart pacing (default) speeds up idle time, waits and typing with smooth ramps while every action and its result play at 1×, the camera zooms on taps and typing, your step captions become on-screen captions, touches get ripples (macOS: a re-drawn pointer), and decorated presets get a device frame or window chrome on a background. Returns the rendered length, zooms, captions and a pre-export check per preset (App Preview rules, license). Fast: nothing is encoded until `export`.

Parameter	Type	Description
captions	array	Caption edits by step number (as end_take lists).
cut	string	shared (default): one cut fitted to every preset's length rules; per_preset: each preset its own length (e.g. a 30 s App Preview and a 45 s X video).
pacing	string	smart (default): speed up idle time, loading waits and typing with smooth ramps; off: cut idle time instead (jump cuts).
presets	array	Presets the cut must suit (their length rules apply), e.g. app_preview_iphone, x_16x9, tiktok_9x16. Default: the platform's App Preview + X + TikTok.
reset	boolean	Back to automatic zooms, captions, speed and full length first.
slow_mo	array	Step numbers (from 1) to play at 0.5× from just before the action until its result settles: the hero moment. Replaces the saved list, [] clears it.
speed	array	Manual speed segments (raw take times; replaces the saved list, [] clears it). They win over pacing, eased in and out.
style	object
take_id required	string	Take to render (from end_take).
trim	object
zooms	array	Replace the automatic zooms (raw take times).

export

Encode a take (as last rendered, else with defaults) for each preset into MP4 files and validate them. App Previews are frameless, 30 fps, H.264 High <= 4.0 with a stereo AAC track and must be 15-30 s; the validator blocks any that break Apple's rules. Free plan: x_16x9 only, watermarked. Returns each file with its measured format.

Parameter	Type	Description
all_sizes	boolean	With bundle app_store: every accepted screenshot size.
bundle	string	Export a whole folder with README.md (what to upload where): app_store = the platform's App Preview + the required App Store screenshot sizes (exports/app-store); launch = YouTube/Product Hunt, X, TikTok/Reels/Shorts and LinkedIn videos + Product Hunt gallery/thumbnail, Open Graph, X, LinkedIn and square images (exports/launch-kit). Pro.
codec	string	Opt-in codec (default h264). App Previews: prores_422_hq (.mov, large files) or hevc (not on Apple's spec page: warned); other presets: hevc.
fps	integer	60 for appstore_header / appstore_search_3x2 (Apple allows 30 or 60).
headline	string	With bundle launch: headline on the images (default: the take title).
icon	string	With bundle launch: app icon image for the Product Hunt thumbnail.
out_dir	string	Destination folder (default: the take's exports folder).
presets	array	Output presets: app_preview_iphone, app_preview_iphone_55, app_preview_ipad, app_preview_mac, appstore_header, appstore_search_3x2, x_16x9, x_1x1, x_9x16, tiktok_9x16, youtube_16x9, linkedin_16x9, linkedin_1x1.
screenshot_style	string	With bundle: raw (default) or marketing App Store screenshots.
screenshots	boolean	Also write App Store screenshots from the take's key frames.
take_id required	string	Take to export.

import_video

Turn a manual recording (QuickTime, Simulator, Device MCP: ~/Movies/Device MCP/*.mov) into a take: ShowTake finds where the action is (changed areas, scrolls, screen transitions), cuts idle time and plans zooms, then `render` / `export` work as for a filmed take. Without `path` it lists recent recordings.

Parameter	Type	Description
keep_idle	boolean	Keep the whole recording instead of cutting idle time.
path	string	The .mov/.mp4/.m4v file (omit to list recent recordings).
platform	string	What was recorded (default: portrait = ios, landscape = macos).
project	string	Library project to file the take under (default: the file name).
title	string	Take title (default: the file name).