👻 phantom-touch

An MCP server for iOS simulator automation — with clipboard-based text input that works with React Native.

phantom-touch gives AI agents full control over iOS simulators: screenshots, element inspection, gestures, app management, and most importantly — reliable text input into React Native forms.

Quick Start

Claude Desktop / Cursor

Add to your MCP configuration:

{
  "mcpServers": {
    "phantom-touch": {
      "command": "npx",
      "args": ["-y", "phantom-touch"]
    }
  }
}

That's it. No cloning, no building — just npx.

The Problem

Every existing iOS MCP tool fails at filling React Native TextInput components because:

• HID keyboard events don't trigger onChangeText
• WebDriverAgent setValue gets overwritten by React state

The Solution

phantom-touch uses a clipboard + paste strategy:

1. simctl pbcopy → set simulator clipboard
2. idb tap → focus the field
3. Cmd+V → paste triggers onChangeText ✅

16 MCP Tools

Module	Tools
Simulator	pt_list_simulators, pt_boot_simulator, pt_shutdown_simulator
App	pt_launch_app, pt_terminate_app, pt_list_apps, pt_open_url
Screen	pt_screenshot, pt_list_elements, pt_get_screen_size
Gesture	pt_tap, pt_swipe
Input ⭐	pt_type_text, pt_press_button, pt_set_clipboard, pt_get_clipboard

Prerequisites

• macOS with Xcode installed
• iOS Simulator
• IDB (iOS Development Bridge): brew install idb-companion
• Node.js 18+

Usage Examples

Once configured, ask your AI agent:

• "Take a screenshot of the simulator"
• "List all UI elements on screen"
• "Tap the Create Account button at (200, 500)"
• "Type 'hello@example.com' into the email field at (200, 450)"
• "Open the deep link myapp://login"

Text Input Strategies

paste (default, recommended)

Uses clipboard + Cmd+V. Works with React Native controlled TextInput.

pt_type_text(text: "Hello", x: 200, y: 400, strategy: "paste")

keyboard

Uses HID keyboard events. Faster but may fail with React Native.

pt_type_text(text: "Hello", x: 200, y: 400, strategy: "keyboard")

Development

git clone https://github.com/hieudtr8/phantom-touch.git
cd phantom-touch
npm install
npm run build
npm run dev   # Run in dev mode with tsx

License

MIT