iphone

This MCP server exposes a REST-like interface for automating an iPhone via Appium. It provides tools to retrieve device information, enumerate installed apps, capture screenshots along with an XML representation of the UI, and perform common interactions such as tapping, swiping, and text input. You can launch or switch apps by bundle ID and query the current foreground bundle. The server streams device UI information and screenshot data for integration with clients like Cherry Studio. To begin, start the MCP server using the provided start script or the Python module, then issue commands under the /mcp namespace to invoke the available tools. The tool names typically follow the pattern iphone_<operation> and map to Appium/XCUIElement interactions behind the scenes.

Prerequisites

• Python 3.8 or later
• Node.js and npm (for Appium and related tooling)
• iPhone with UDID
• Xcode

Steps

1. Clone the repository and navigate to the project directory: git clone https://github.com/Lakr233/iphone-mcp.git && cd iphone-mcp
2. Set up a Python virtual environment and activate it: python -m venv .venv && source .venv/bin/activate
3. Install Python dependencies: pip install -r requirements.txt
4. Install Appium and drivers (Node.js required): npm install -g appium && appium driver install xcuitest
5. Ensure WebDriverAgent setup per Appium xcuitest driver guide: https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda/
6. Configure the server by editing the start script with your device UDID, then start the server: ./start.sh
7. Access the MCP interface at http://127.0.0.1:8765/mcp using the default settings, or adjust SERVER_HOST/PORT via environment variables as needed.

Notes and tips:

• DEVICE_UDID is required for all operations.
• You can configure Appium host/port, and MCP server host/port/path via environment variables described in the mcp_config.
• The server provides: iphone_device_info, iphone_device_apps, iphone_interface_snapshot, iphone_interface_elements, iphone_operate_click, iphone_operate_swipe, iphone_operate_text_input, iphone_operate_app_launch, iphone_operate_get_current_bundle_id.
• For large UI trees, use the optimized XML output option to minimize token usage; consider streaming screenshots to reduce memory load.
• If you encounter connection issues with Appium, verify that the xcuitest driver is installed and that WebDriverAgent can communicate with the iPhone over USB/Wi‑Fi.
• Run tests with pytest to ensure compatibility with your Python environment.