home / mcp / iphone mcp server

iPhone MCP Server

A Model Context Protocol (MCP) server for automating iPhone tasks with Appium. Supports app control, UI interactions, and screenshot capture via streamable HTTP.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "lakr233-iphone-mcp": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "LOG_LEVEL": "info",
        "APPIUM_HOST": "127.0.0.1",
        "APPIUM_PORT": "4723",
        "DEVICE_UDID": "YOUR_DEVICE_UDID",
        "SERVER_HOST": "127.0.0.1",
        "SERVER_PATH": "/mcp",
        "SERVER_PORT": "8765"
      }
    }
  }
}

You can automate iPhone tasks with this MCP server, which exposes device information, UI interactions, and screenshot capture through a streamlined HTTP interface. It’s designed to work with Appium and provides convenient endpoints to control apps, simulate touches, and retrieve UI structure, helping you build reliable automation flows for iPhone tasks.

How to use

Start the MCP server and connect through the local HTTP endpoint. Use your MCP client to send requests to the server to retrieve device info, list installed apps, capture UI snapshots, and perform touch operations. You can launch or switch apps using bundle IDs and capture a streamable interface snapshot that includes both the screenshot and structured XML representation of the UI.

How to install

Prerequisites you need before installing the MCP server are as follows.

Python 3.8 or later

Node.js
npm

iPhone device with a valid UDID

Xcode installed on macOS

Proceed with the following steps to set up the MCP server and its environment.

git clone https://github.com/Lakr233/iphone-mcp.git && cd iphone-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm install -g appium
appium driver install xcuitest
# Set up WebDriver Agent according to your environment
# Configure your device UDID in the startup script below

Configuration and startup

Configure the startup script to use your iPhone UDID and desired host/port settings. You will run the startup script to launch Appium and the MCP server together.

# Edit start.sh to set your device UDID and any host/port overrides
# Example environment variable setup in the script
export DEVICE_UDID=YOUR_DEVICE_UDID
export APPIUM_HOST=127.0.0.1
export APPIUM_PORT=4723
export SERVER_HOST=127.0.0.1
export SERVER_PORT=8765
export SERVER_PATH=/mcp
export LOG_LEVEL=info

# Start the server (the exact command may vary by setup)
./start.sh

Connecting to the server

Once the server starts, you can access the MCP endpoint at the following URL using your MCP client: http://127.0.0.1:8765/mcp. From there, you can issue requests to obtain device info, list apps, capture UI snapshots, enumerate elements, and perform actions like taps, swipes, text input, and app launches.

Additional usage notes

The server exposes a set of tools you can invoke via the MCP client to interact with the iPhone. You can obtain device details, list installed apps, capture interface snapshots, enumerate UI elements, and perform common interactions such as tapping, swiping, and entering text. You can also launch apps by bundle ID and retrieve the current bundle ID of the active app.

Notes on environment and dev setup

Environment variables to configure for the MCP server are defined in the startup script. You will typically set the device UDID, Appium host/port, server host/port/path, and log level. Use these to tailor the runtime to your local machine and network.

Troubleshooting

If the server fails to start, verify that the UDID is correct, ensure Appium and WebDriver Agent are properly configured, and confirm that the port 8765 (or your chosen port) is not blocked by a firewall. Check logs for error messages related to device connection, WebDriver Agent setup, or Appium driver initialization.

Available tools

iphone_device_info

Get device details such as model, OS version, and UDID.

iphone_device_apps

List installed apps on the iPhone.

iphone_interface_snapshot

Capture a screenshot and associated XML representation of the UI.

iphone_interface_elements

List UI elements available in the current interface.

iphone_operate_click

Perform a tap on a specified UI element or coordinate.

iphone_operate_swipe

Perform a swipe gesture in a specified direction or area.

iphone_operate_text_input

Input text into a focused field or element.

iphone_operate_app_launch

Launch an app by bundle ID or bring it to foreground.

iphone_operate_get_current_bundle_id

Return the bundle ID of the currently active app.