ZeptapTool reference
Every tool the Zeptap MCP server exposes - arguments, defaults, what each returns, and what it needs connected.
Zeptap exposes 17 tools. The live schema is the tools/list response; this page adds the defaults, return values and requirements the schema doesn't state.
Conventions
- Coordinates are integer pixels in the most recent screenshot, origin top-left. On a typical iPhone the screenshot is 591×1280; the size is printed with every screenshot (
Screenshot 591x1280 px.). - Returns a screenshot means the result holds a text note (what happened, and whether the screen settled) plus a JPEG of the screen, taken after the pointer is parked and the frames stop changing (up to 3 s).
- Errors come back as a normal tool result with
isError: trueand a text message saying why. A failed action changes nothing on the phone unless the message says otherwise. - Needs: USB for the screen, Bluetooth for touch and keyboard. A Bluetooth tool called while Bluetooth is disconnected returns
Not connected to the iPhone over Bluetooth…and does nothing.
Seeing
screenshot
Capture the screen once it settles. No arguments.
Returns a screenshot. Needs USB.
find_text
On-device OCR of the current screen. Returns each text line, top to bottom, with its center and bounding box in screenshot pixels:
screenshot 591x1280, 2 lines:
"General" center=(160,512) box=(96,498,128,28)
"Accessibility" center=(186,590) box=(96,576,180,28)| Argument | Type | Default | Meaning |
|---|---|---|---|
query | string | none | Keep only lines containing this text, case-insensitive |
exact | boolean | false | Match the whole line instead of a substring |
Returns text only. Needs USB.
wait
Wait, then return a settled screenshot. Use it for loading screens and animations.
| Argument | Type | Default |
|---|---|---|
ms | integer | 1000 |
Needs USB.
Touching
All touch tools return a screenshot and need Bluetooth (and USB for the screenshot).
tap
Tap a point. Arguments: x, y (required).
tap_text
Find visible text with OCR and tap its center. When the text isn't on screen, nothing is tapped and the result is an error with a screenshot.
| Argument | Type | Default | Meaning |
|---|---|---|---|
text | string | required | The label to tap |
exact | boolean | true | Match the whole line. Set false to match a substring |
index | integer | 0 | Which match to tap, counting from the top |
double_tap
Double tap a point, for zooming or selecting a word. Arguments: x, y (required).
long_press
Press and hold, for context menus and drag handles.
| Argument | Type | Default |
|---|---|---|
x, y | integer | required |
duration_ms | integer | 800 |
drag
Press at one point, move to another, release. At the default 800 ms there is no momentum and content moves about 0.85× the drag distance. Below about 500 ms, content keeps coasting after release.
| Argument | Type | Default |
|---|---|---|
from_x, from_y, to_x, to_y | integer | required |
duration_ms | integer | 800 |
To reveal content further down a list, drag from a lower point to a higher one.
flick
A fast swipe with momentum, 30% of the screen long, in the finger's direction. up scrolls a long way down a list.
| Argument | Type | Values |
|---|---|---|
x, y | integer | Start point |
direction | string | up, down, left, right |
Typing
type_text
Type into the focused field. Tap the field first.
| Argument | Type |
|---|---|
text | string, required |
Only characters on a US keyboard (printable ASCII, newline, tab) can be typed. If any character is unsupported, nothing is typed and the error lists the characters. iOS autocorrect, auto-capitalization and smart quotes can still change what appears, so check the returned screenshot. Needs Bluetooth.
press_key
Press one key, optionally with modifiers.
| Argument | Type | Values |
|---|---|---|
key | string, required | enter, escape, backspace, tab, space, arrow_up, arrow_down, arrow_left, arrow_right, a, c, v, x, z |
modifiers | string[] | command, shift, control, alternate |
repeat | integer | Default 1 |
key: "a" with modifiers: ["command"] selects all. Returns a screenshot. Needs Bluetooth.
Navigating
All navigation tools take no arguments except open_app, return a screenshot, and need Bluetooth.
| Tool | Does |
|---|---|
home | Go to the Home Screen. Closes Spotlight, menus and Control Center on the way |
back | Go back one screen with an edge swipe from the left |
dismiss | Close Spotlight, menus, sheets or the keyboard (Escape twice) |
open_app | Open an installed app by its exact name, via Spotlight |
open_app
| Argument | Type |
|---|---|
name | string, required. The app's name as shown under its icon, in US-keyboard ASCII |
Zeptap goes home, opens Spotlight, types the name, and taps the matching result. When no result matches, it closes Spotlight, opens nothing, and returns an error. It also returns an error if Spotlight still appears open after the tap.
Lock and unlock
These run in the Zeptap app rather than over the agent's own input, and are covered in full in Lock and unlock.
| Tool | Does | Needs |
|---|---|---|
lock | Lock the iPhone and turn the screen off. Returns text | USB, with the iPhone trusting this Mac |
unlock | Unlock with the passcode saved in Zeptap. One attempt per call. Returns a screenshot when the screen is visible | Bluetooth, a saved passcode, and agents allowed to unlock this iPhone. USB lets Zeptap confirm the result |
The agent never sees or sends the passcode. When unlock fails, report the message to the user; a second call won't succeed where the first failed.