Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
IPHONE_MCP_MODENoConnection mode: auto (default), usb or wifi.
IPHONE_MCP_UDIDNoPick a device when several iPhones are connected.
IPHONE_MCP_TEAM_IDNoSigning team ID for setup.
IPHONE_MCP_WDA_REFNoWebDriverAgent release to build or download (default: a tested one).
IPHONE_MCP_WDA_URLNoFixed WebDriverAgent address, e.g. http://192.168.1.42:8100.
IPHONE_MCP_LAUNCHERNoLauncher to use: xcodebuild (default on macOS) or pymobiledevice3.
IPHONE_MCP_BUNDLE_IDNoBundle ID for setup.
IPHONE_MCP_KEEP_AWAKENo1 (default) keeps the screen awake while connected, 0 turns it off.
IPHONE_MCP_RUNNER_BUNDLE_IDNoBundle ID of an installed WebDriverAgent runner for no-Xcode launch.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

Controls a real, physical iPhone. Coordinates are iOS points, not pixels: iphone_screenshot returns an image scaled to points, so a position in the image can be passed straight to iphone_tap. Typical loop: look (iphone_ui_tree is cheaper and more precise, iphone_screenshot for visuals) → act (iphone_tap_text / iphone_tap / iphone_swipe / iphone_type) → iphone_wait_for or look again. If there is no connection, call iphone_start_agent first. While connected, the screen is kept from auto-locking (iphone_keep_awake). If the iPhone is locked, a passcode must be entered by the user. Ask the user before anything with real-world effect (sending messages, purchases, payments, deleting data, changing account or security settings).

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
iphone_statusA

Report the iPhone connection and state: device and iOS version, connection route (USB or Wi-Fi), screen size in points, whether it is locked, whether keep-awake is on, and the foreground app.

Use it first in a session and whenever an action fails, to decide whether to call iphone_start_agent
(no connection) or ask the user to unlock (locked). Reads only; changes nothing on the phone.
iphone_start_agentA

Start WebDriverAgent on the iPhone and connect to it – required before any other iphone_* action.

Call it when iphone_status or another tool reports no connection. It is safe to call again: if the
agent already runs it just reports the connection. Starting takes 10–90 s, works over cable or Wi-Fi
and needs the iPhone unlocked; if it is locked, the result says so and the user must unlock it.
Returns the connection route on success or a concrete reason on failure.
iphone_stop_agentA

Stop WebDriverAgent on the iPhone and close the connection.

Use it when the session is finished, so the automation port on the phone is no longer open. Afterwards
every other iphone_* tool fails until iphone_start_agent is called again. Leaves apps and data untouched.
iphone_keep_awakeA

Turn the no-auto-lock behaviour on or off for this session. It is on by default.

While on, an invisible touch just outside the screen is sent every 10 s, which iOS counts as activity;
no settings are changed and it ends with the session. Turn it off if the user wants the phone to lock.
It cannot unlock a phone that is already locked – use iphone_lock for that.
iphone_screenshotA

Capture the current iPhone screen as a JPEG image scaled to iOS points, plus its size.

Because the image is in points, any pixel position in it can be passed unchanged to iphone_tap or
iphone_swipe. Use it to see visual content (images, colours, layout, games). To find buttons or read
text, iphone_ui_tree is cheaper and gives exact positions. Reads only; adds a note if the phone is locked.
iphone_ui_treeA

List the visible UI elements of the current screen as text, one per line: [Type] "label" value=… @(center x,center y) width×height, indented by nesting, all in iOS points.

Prefer this over iphone_screenshot to find buttons, fields and text and to read values: it is cheaper
and positions are exact. Pass the center point to iphone_tap, or use iphone_tap_text with the label.
Reads only; adds a note if the phone is locked.
iphone_wait_forA

Wait until an element with the given text appears on screen (or disappears with gone=true).

Use it after an action that triggers loading, navigation or an animation, instead of guessing a delay or taking repeated screenshots. Polls about twice a second and returns as soon as the condition holds, with the element's position, or reports a timeout. Reads only.

iphone_tapA

Touch the screen at a coordinate: single tap, double tap or long press.

Use it when you know the position – from iphone_ui_tree (center point) or iphone_screenshot (pixel =
point). To hit an element by its visible text, iphone_tap_text is more robust. The touch acts on
whatever is at that point, like a finger would; it does not wait for the app to finish reacting, so
look again (or call iphone_wait_for) before the next step.
iphone_tap_textA

Find a visible element by its text and tap its center.

Prefer this over iphone_tap for buttons, cells and links with a label: it does not depend on layout or
screen size. If nothing matches, it says so and taps nothing; with several matches it reports how many
there are so you can pick another with `index`. Like a finger tap, the effect depends on the element.
iphone_swipeA

Drag one finger from a start point to an end point.

Use it for precise drags: sliders, reordering, swiping a cell to reveal actions, pulling down the
notification area or a sheet. For plain scrolling of a list or page, iphone_scroll is simpler.
Swipes starting at the very bottom or top edge trigger iOS system gestures (home, notifications).
iphone_scrollA

Scroll the content in the middle of the screen in a direction.

Use it to reach items outside the visible area of lists, pages and carousels, then call iphone_ui_tree
again. It starts in the screen center, so it never triggers system edge gestures; for exact drags use
iphone_swipe.
iphone_pinchA

Two-finger pinch gesture to zoom in or out, e.g. in Maps, Photos or a web page.

Use it only where content is zoomable; elsewhere it usually has no effect. Single-finger gestures are
covered by iphone_tap, iphone_swipe and iphone_scroll.
iphone_typeA

Type text into the text field that currently has keyboard focus.

Tap the field first (iphone_tap_text or iphone_tap) so the keyboard is open; without a focused field
the call fails. Text is appended at the cursor, not replacing existing content. Never use it for
passwords or passcodes – ask the user to enter those.
iphone_press_buttonA

Press a hardware button of the iPhone.

iPhones have no back button: to go back inside an app, tap its back button (often top left, see
iphone_ui_tree). To leave an app use 'home'; to quit it completely use iphone_close_app; to lock the
screen use iphone_lock.
iphone_lockA

Lock the iPhone, or wake and unlock it.

'unlock' only completes on phones without a passcode; with a passcode or Face ID it wakes the screen
and reports that the user must unlock – never try to enter a passcode. Use iphone_status to see the
current lock state and iphone_keep_awake to prevent auto-lock.
iphone_list_appsA

List the apps installed on the iPhone as 'Name — bundle ID' lines, sorted by name.

Use it to find the exact bundle ID or name for iphone_launch_app / iphone_close_app when a name is
ambiguous or not found. Needs the cable or Wi-Fi sync; otherwise it lists the built-in Apple apps it
knows. Reads only.
iphone_launch_appA

Open an app, or bring it to the front if it is already running (its state is kept).

Faster and more reliable than finding and tapping its icon on the home screen. To start an app fresh,
call iphone_close_app first. To open a specific page or link inside an app, use iphone_open_url.
iphone_close_appA

Force-quit an app, like swiping it away in the app switcher.

Use it to reset an app to a fresh start or to stop something running. Unsaved input in that app (for
example a half-written message) can be lost, so prefer iphone_press_button('home') to just leave it.
iphone_open_urlA

Open a web page in Safari or a deep link in the app that handles it.

Use it to jump straight to a page or screen instead of navigating by taps. Links with tel:, sms:,
mailto: or payment schemes start real actions or drafts on the phone – ask the user first. iOS may show
a confirmation dialog; check with iphone_ui_tree afterwards.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4.4/5.0

Scored across 19 tools

Disambiguation5/5

The tools are cleanly separated by resource and action: session lifecycle, screen reading, gestures, text input, app control, and device locking. Overlaps such as tap vs tap_text, swipe vs scroll, and screenshot vs ui_tree are explicitly resolved in descriptions, so an agent can choose confidently.

Naming Consistency5/5

All 19 tools use the iphone_ prefix and snake_case, yielding a predictable namespace. The only minor variation is that a few are noun-style read operations (iphone_status, iphone_screenshot, iphone_ui_tree) while most are verb-led, but the convention remains consistent and readable.

Tool Count4/5

19 tools is slightly above the typical sweet spot but justified for a device-automation surface. Each tool covers a distinct capability, and no obvious redundant wrappers inflate the count.

Completeness4/5

Core lifecycle, observation, gesture, text-entry, app, and URL operations are covered, giving no major dead ends for UI automation. Minor gaps remain around clearing/replacing text, device settings, notifications, or advanced multi-touch, but these are outside the apparent scope.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues