# MCP tool reference

> Every tool the ShowTake MCP server offers, with its parameters, generated from the server's own catalogue.

Source: https://showtake.app/docs/tools

Tool names are a stable contract: they are never renamed, only added. All tools return JSON; errors are `{ "error": "<code>", "hint": "…" }` ([error codes](https://showtake.app/docs/troubleshooting)).

## `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). |

## `send_feedback`

Send a bug report, idea, question or praise to the ShowTake team, with optional evidence: files (video, images, logs, JSON, YAML, PDF, ZIP), takes and a screenshot of ShowTake, plus redacted diagnostics (doctor, recent tool calls and errors, crash summaries). Nothing is sent by this call: ShowTake opens its Send Feedback window with the report and the user presses Send. Waits up to wait_seconds for that; returns status sent (+ reference), cancelled, queued (offline, sent later) or awaiting_user (+ draft_id and tell_user). With draft_id: the status of an earlier report.

| Parameter | Type | Description |
| --- | --- | --- |
| `attachments` | array | Evidence the user agreed to send (20 at most, 1 GB in total; videos up to 500 MB). |
| `contact_email` | string | Email for the reply (only if the user gave it). |
| `draft_id` | string | Check an earlier report that was awaiting_user (other fields ignored). |
| `include_diagnostics` | boolean | Attach the redacted diagnostics (default true). |
| `kind` | string | What it is (default bug). |
| `message` | string | What was done (tool calls, take ids, error codes), what was expected, what happened. Plain text, up to 20000 characters. |
| `screenshot` | boolean | Also attach a screenshot of ShowTake's main window. |
| `wait_seconds` | integer | How long to wait for the user's Send (default 90, max 300). |

## `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). |