Skip to main content
Glama

CI PyPI Python MCP Platforms License: GPL v3 Sponsor

An MCP server that gives Claude Code, OpenAI Codex and any other MCP clienteyes and hands on a real, physical iPhone – over a cable or Wi-Fi.

Quick start · Tools · Wi-Fi · Linux & Windows · Safety · Troubleshooting · Sponsor ❤


✨ Highlights

👀 Sees the screen

Screenshots come scaled to iOS points, so every pixel the model sees is a coordinate it can tap. The UI tree turns the screen into compact text with labels and positions. It is faster, cheaper and more precise than pixels.

👆 Acts like a person

Tap, double-tap, long-press, tap by text, swipe, scroll, pinch-zoom, type, press Home and the volume buttons, and wait for text to appear instead of guessing delays. It can also launch apps by name ("Settings", "Einstellungen") and open URLs and deep links.

📶 Cable or Wi-Fi

It picks the best route on its own: the Xcode tunnel, then usbmux, then the iPhone's last known Wi-Fi IP. If the cable drops out, it reconnects over Wi-Fi.

🔆 Stays awake

While an agent is connected, the screen doesn't auto-lock. It sends an invisible touch just outside the display, and no settings are changed. This works even in Low Power Mode, where Auto-Lock is fixed at 30 s.

🔐 Your device, your signature

No jailbreak, no third-party cloud. WebDriverAgent is built and signed with your own Apple ID (a free one works), and all traffic stays between your computer and your phone.

🐧 Not only macOS

On Linux and Windows, WebDriverAgent starts without Xcode through pymobiledevice3's root-free tunnel. iphone-mcp doctor checks the whole chain.

Related MCP server: Zeptap

🚀 Quick start

You need: uv, an iPhone with an Apple ID, and a Mac with Xcode (for Linux / Windows see below).

1 · Prepare the iPhone (once)

  • Connect it by cable, unlock it and tap Trust.

  • Settings → Privacy & Security → Developer Mode → on (the phone restarts).

  • Settings → Developer → Enable UI Automation → on.

2 · Build WebDriverAgent (once, and again after Xcode updates)

uvx iphone-mcp doctor     # checks Xcode, signing, iPhone
uvx iphone-mcp setup      # builds & installs WebDriverAgent, signed with your Apple ID

3 · Add it to your agent

claude mcp add iphone -s user -- uvx iphone-mcp

~/.codex/config.toml

[mcp_servers.iphone]
command = "uvx"
args = ["iphone-mcp"]
tool_timeout_sec = 180   # starting the agent can take a minute
{
  "mcpServers": {
    "iphone": { "command": "uvx", "args": ["iphone-mcp"] }
  }
}
git clone https://github.com/DamienDrash/iphone-mcp.git && cd iphone-mcp
uv run iphone-mcp setup
claude mcp add iphone -s user -- uv --directory "$PWD" run iphone-mcp

4 · Ask, for example:

“Start the iPhone agent, open Settings and tell me which Wi-Fi I'm on.”

“Open the App Store, search for ‘Duolingo’ and show me the rating – don't install anything.”

“Test the sign-up flow of my TestFlight build and screenshot every step.”

🧠 How it works

flowchart LR
    A["Claude Code · Codex<br/>any MCP client"] -- stdio --> B["iphone-mcp"]
    B -- "HTTP :8100<br/>Xcode tunnel · usbmux · Wi-Fi IP" --> C["WebDriverAgent<br/>on the iPhone"]
    B -. "launch: xcodebuild (macOS)<br/>or pymobiledevice3 (any OS)" .-> C
    C -- XCUITest --> D["iOS UI"]

WebDriverAgent is the XCUITest-based agent that Appium also uses. It runs as a test runner on the iPhone and exposes the UI over HTTP. iphone-mcp:

  • builds or installs it,

  • starts it with xcodebuild or with pymobiledevice3's XCUITest service,

  • keeps one connection alive across cable and Wi-Fi,

  • turns it all into a handful of tools a model can use well.

🧰 Tools

Tool

What it does

iphone_start_agent · iphone_stop_agent

Start / stop WebDriverAgent (cable or Wi-Fi)

iphone_status

Connection, screen size, lock state, keep-awake, foreground app

iphone_screenshot

Screenshot scaled to iOS points – image pixels = tap coordinates

iphone_ui_tree

Visible elements with text and center point

iphone_wait_for

Wait until a text appears (or disappears) – no guessing of delays

iphone_tap

Tap, double-tap or long-press at coordinates

iphone_tap_text

Tap the element showing a given text

iphone_swipe · iphone_scroll

Swipe / scroll in any direction

iphone_pinch

Two-finger pinch to zoom in or out

iphone_type

Type into the focused field, optionally press Return

iphone_press_button

Home, volume up, volume down

iphone_lock

Lock, or wake/unlock (without passcode)

iphone_keep_awake

Turn the no-auto-lock behaviour on or off

iphone_list_apps · iphone_launch_app · iphone_close_app

List, launch (name or bundle ID), terminate apps

iphone_open_url

Open a URL or deep link

📶 Wi-Fi

  1. Connect the iPhone by cable once. In Xcode open Window → Devices and Simulators, select the iPhone and tick Connect via network.

  2. Put the iPhone and your Mac on the same Wi-Fi. The iPhone must be on Wi-Fi, not only on mobile data.

  3. Unplug. uvx iphone-mcp doctor should now say connected via Wi-Fi.

iphone-mcp uses the tunnel that Xcode itself keeps to the phone. That tunnel works the same over cable and Wi-Fi, so a flaky cable is not a problem once Wi-Fi is set up.

🔆 Screen lock

Situation

What happens

Agent connected

Keep-awake stops the screen from auto-locking. Turn it off with iphone_keep_awake(false) or IPHONE_MCP_KEEP_AWAKE=0.

Phone already locked

The tools say so. The agent can wake the screen; you enter the passcode or use Face ID – the agent can't, by design.

Starting the agent

Needs an unlocked iPhone (Xcode's rule). The agent is told to ask you, and the start continues by itself once you unlock.

🐧 Linux & Windows

Everything except building WebDriverAgent works without a Mac. iphone-mcp starts WebDriverAgent through pymobiledevice3's XCUITest service and its root-free userspace tunnel (iOS 17.4+), over USB or Wi-Fi.

uvx iphone-mcp setup --prebuilt          # downloads Appium's prebuilt, unsigned WebDriverAgent (.ipa)
# sign it with your Apple ID – Sideloadly (Windows, free Apple ID) or zsign (Linux, paid account)
uvx iphone-mcp setup --ipa signed.ipa    # installs it over USB and remembers its bundle ID
uvx iphone-mcp start                     # or let your agent call iphone_start_agent

macOS

Linux

Windows

Build & sign WebDriverAgent

✅ setup

➖ sign the prebuilt .ipa

➖ sign the prebuilt .ipa

Install WebDriverAgent

✅

✅ setup --ipa

✅ setup --ipa

Start WebDriverAgent

✅ Xcode or pymobiledevice3

✅ pymobiledevice3

✅ pymobiledevice3

Control over USB

✅

✅ needs usbmuxd

✅ needs Apple Devices / iTunes

Control over Wi-Fi

✅

✅ IPHONE_MCP_MODE=wifi after one USB pairing

✅ IPHONE_MCP_MODE=wifi after one USB pairing

You can also leave WebDriverAgent running from a Mac and drive it from anywhere on the network:

IPHONE_MCP_WDA_URL=http://<iphone-ip>:8100 uvx iphone-mcp
NOTE

What is tested so far: the no-Xcode path – installing with setup --ipa and starting through pymobiledevice3 – on macOS against a real iPhone (iOS 26.6) over usbmux Wi-Fi sync. Not tested yet: USB, the pure RemotePairing Wi-Fi mode (IPHONE_MCP_MODE=wifi) and real Linux / Windows machines. Reports are very welcome – please open an issue with the output of iphone-mcp doctor.

⌨️ Command line

Command

iphone-mcp

Run the MCP server on stdio (what your client starts)

iphone-mcp doctor

Check Xcode / signing / iPhone / connection

iphone-mcp setup [--udid …] [--team …]

Build & install WebDriverAgent with Xcode

iphone-mcp setup --prebuilt · --ipa FILE

Without Xcode: download the prebuilt app / install a signed one

iphone-mcp start · stop

Start / stop WebDriverAgent without an MCP client

⚙️ Configuration

Environment variable

Meaning

IPHONE_MCP_UDID

Pick a device when several iPhones are connected

IPHONE_MCP_MODE

auto (default), usb or wifi

IPHONE_MCP_WDA_URL

Fixed WebDriverAgent address, e.g. http://192.168.1.42:8100

IPHONE_MCP_KEEP_AWAKE

1 (default) keeps the screen awake while connected, 0 turns it off

IPHONE_MCP_LAUNCHER

xcodebuild (default on macOS) or pymobiledevice3

IPHONE_MCP_TEAM_ID · IPHONE_MCP_BUNDLE_ID

Signing team and bundle ID for setup

IPHONE_MCP_RUNNER_BUNDLE_ID

Bundle ID of an installed WebDriverAgent runner (no-Xcode launch)

IPHONE_MCP_WDA_REF

WebDriverAgent release to build or download (default: a tested one)

iphone-mcp writes files only to these places, never to your project:

What

macOS

Linux / Windows

Config

~/.config/iphone-mcp/

~/.config/iphone-mcp/

WebDriverAgent source and builds

~/Library/Application Support/iphone-mcp/

~/.local/share/iphone-mcp/

Logs

~/Library/Logs/iphone-mcp/

~/.local/share/iphone-mcp/logs/

🛡️ Safety

This gives an AI agent hands on your real phone, with your accounts, messages and payment methods.

  • The server tells the agent to ask before anything with real-world effect: sending messages, purchases, payments, deleting data, changing account or security settings. Watch what it does anyway, and keep your client's tool approvals on.

  • iphone-mcp never types passwords or passcodes.

  • While WebDriverAgent runs, it listens on port 8100 on the iPhone without authentication. Use trusted networks only, and stop it when you're done (iphone-mcp stop).

See SECURITY.md for how to report vulnerabilities.

🩺 Troubleshooting

Symptom

Fix

Unable to find a destination matching … id:

The iPhone isn't connected right now – replug, unlock, run iphone-mcp doctor.

“Unlock … to Continue” / “device is locked”

Unlock the iPhone; the start continues by itself.

unavailable after unplugging

Wi-Fi isn't set up – see Wi-Fi. Is the iPhone on the same Wi-Fi as the computer?

Signing errors during setup

Xcode → Settings → Accounts: sign in. Use --team if you're in several teams.

Worked yesterday, not today (free Apple ID)

The signature expired after 7 days – run iphone-mcp setup again.

Runner exits immediately

Settings → Developer → Enable UI Automation, and trust the developer app under General → VPN & Device Management.

Logs: ~/Library/Logs/iphone-mcp/wda.log (runtime) and build.log (setup).

🤝 Contributing

Issues and pull requests are welcome – see CONTRIBUTING.md. Run the checks with:

uv sync && uv run pytest && uv run ruff check . && uv run ruff format --check .

👤 Author

Built by Damien Frigewski – @DamienDrash.

💖 Support the project

iphone-mcp is free and open source, and it stays that way. If it saves you time, you can support its development through GitHub Sponsors. Monthly and one-time options are available, and every amount helps. Sponsors get nothing extra in the software; it's simply a thank-you that keeps the work going.

A ⭐ on GitHub helps too – it makes iphone-mcp easier for others to find.

📄 License & credits

GPL-3.0-or-later. The GPL follows from pymobiledevice3, which iphone-mcp builds on.

WebDriverAgent (BSD-3-Clause, © Meta Platforms and Appium contributors) is downloaded and built or installed on your own machine; it is not redistributed here.

Not affiliated with Apple. iPhone, iOS and Xcode are trademarks of Apple Inc.

Available Tools

19 tools
iphone_close_appA
DestructiveIdempotent

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.

Inputs: app (required). Returns: result

iphone_keep_awakeA
Idempotent

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.

Inputs: enabled (required). Returns: result

iphone_launch_appA
Idempotent

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.

Inputs: app (required). Returns: result

iphone_list_appsA
Read-onlyIdempotent

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.

Inputs: filter. Returns: result

iphone_lockA
Idempotent

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.

Inputs: action (required). Returns: result

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.

Inputs: url (required). Returns: result

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.

Inputs: scale (required), x, y. Returns: result

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.

Inputs: button (required). Returns: result

iphone_screenshotA
Read-onlyIdempotent

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.

Inputs: quality.

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.

Inputs: direction (required), amount. Returns: result

iphone_start_agentA
Idempotent

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.

Inputs: no named parameters. Returns: result

iphone_statusA
Read-onlyIdempotent

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.

Inputs: no named parameters. Returns: result

iphone_stop_agentA
Idempotent

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.

Inputs: no named parameters. Returns: result

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

Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +1 more. Returns: result

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.

Inputs: x (required), y (required), gesture, hold_seconds. Returns: result

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.

Inputs: text (required), exact, index. Returns: result

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.

Inputs: text (required), submit. Returns: result

iphone_ui_treeA
Read-onlyIdempotent

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.

Inputs: max_lines. Returns: result

iphone_wait_forA
Read-onlyIdempotent

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.

Inputs: text (required), gone, exact, timeout. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      A
      maintenance
      Control a real iPhone or iOS Simulator through a macOS daemon and XCTest runner over USB or Wi-Fi: read screen text, tap, type, swipe, inspect logs and replay flows with explicit outcomes. Browser sandbox: use readonly to inspect 12 preloaded flows without a phone. Reuse an existing sandbox from MCP Deployments, or delete it before starting another. Device control needs your Mac and iPhone.
      6
      43
      505
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to operate a real iPhone from a Mac by reading the screen over USB and sending taps, swipes, typing, and app launches over Bluetooth, with every action returning a fresh screenshot so the agent can verify its work. Runs as a local MCP server, so agents can test iOS apps on physical devices and automate everyday phone tasks.
      40 npm
      10
      MIT
    • A
      license
      B
      quality
      F
      maintenance
      Enables AI agents to see and operate a real USB-connected iPhone from a Linux Docker host — taking screenshots with region zoom, reading the element tree, tapping, swiping, long-pressing, typing text, pressing hardware buttons, listing/launching/terminating apps, and opening URLs. Automatically recovers from replugs and crashes, re-signs its automation agent before expiry, and falls back to a signing-free HID path on newer iOS.
      13
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Let AI agents operate a real USB-connected iPhone from Linux — no Mac, no jailbreak, no paid developer account. Screenshots, taps, swipes, text input, element tree and app control via WebDriverAgent, with CoreDevice HID fallback.
      17
      42
      MIT