ios-control-mcp

한국어

An MCP (Model Context Protocol) server for automating iOS simulators and real iOS devices. Enables LLMs like Claude to interact with iOS devices.

https://github.com/user-attachments/assets/4284357b-6b6e-4e6a-a81c-e5976052be51

Quick Start

Get started in 30 seconds:

1. Add to your MCP client config:

   {
     "mcpServers": {
       "ios-control": {
         "command": "npx",
         "args": ["-y", "ios-control-mcp"]
       }
     }
   }

2. Ask Claude: "Take a screenshot of the iOS simulator"

That's it! Claude can now control iOS simulators. See Installation for detailed setup instructions.

Features

Device Management

• list_devices - List connected iOS devices (simulators and physical devices)
• select_device - Select device to control by UDID

Screen Information

• get_ui_snapshot - Get UI element tree of all foreground apps
• screenshot - Take a screenshot of the current screen

UI Interactions

• tap - Tap a UI element by its label
• type_text - Type text (optionally into a specific element)
• swipe - Swipe in a direction
• drag - Drag from one element to another by their labels

App & Device Control

• launch_app - Launch an app by its bundle ID
• press_button - Press a hardware button (home, volumeUp, volumeDown)

Requirements

• macOS 13 or later
• Xcode (with iOS Simulator)
• Node.js 18 or later
• For physical devices: Apple Developer Team ID (free or paid)

Installation

Using Simulator (Default)

Simulators work out of the box without additional setup.

Standard config - Works with most MCP clients:

{
  "mcpServers": {
    "ios-control": {
      "command": "npx",
      "args": [
        "-y",
        "ios-control-mcp"
      ]
    }
  }
}

claude mcp add ios-control -- npx -y ios-control-mcp

For physical devices, add the Team ID environment variable:

claude mcp add ios-control -e IOS_CONTROL_TEAM_ID=YOUR_TEAM_ID -- npx -y ios-control-mcp

Follow the MCP installation guide using the standard config above.

Go to Cursor Settings → MCP → Add new MCP Server. Set a name and enter npx -y ios-control-mcp as the command type.

Install via VS Code CLI:

code --add-mcp '{"name":"ios-control","command":"npx","args":["-y","ios-control-mcp"]}'

Or follow the MCP installation guide using the standard config above.

Follow the Windsurf MCP documentation using the standard config above.

Using Physical iOS Devices

Using physical iOS devices requires an Apple Developer Team ID. A free Apple ID works too.

1. Find Your Team ID

Run this command in Terminal to find your Team ID:

security find-identity -v -p codesigning

Example output:

1) ABCDEF1234567890... "Apple Development: [email protected] (XXXXXXXXXX)"

The 10-character string in parentheses (e.g., XXXXXXXXXX) is your Team ID.

Don't have a Team ID? Open any project in Xcode, sign in with your Apple ID, and build to a device once. This will automatically generate a Team ID.

2. Add Team ID to MCP Configuration

{
  "mcpServers": {
    "ios-control": {
      "command": "npx",
      "args": ["-y", "ios-control-mcp"],
      "env": {
        "IOS_CONTROL_TEAM_ID": "YOUR_TEAM_ID"
      }
    }
  }
}

3. Prepare Your Device

1. Enable Developer Mode: Settings → Privacy & Security → Developer Mode → Enable (iOS 16+)
2. Connect via USB: Connect your device to Mac via USB and tap "Trust" when prompted
3. First run: After the app is installed, if you see "Untrusted Developer" warning, go to Settings → General → VPN & Device Management and trust the developer app

Usage Examples

Here are some things you can ask Claude:

Screenshots & UI inspection:

"Take a screenshot of the current screen" "Show me the UI snapshot"

App navigation:

"Open the Settings app" "Launch Safari"

UI interactions:

"Tap the 'Sign In' button" "Type '[email protected]' in the email field" "Swipe up"

License

MIT