iOS MCP Server

MCP server for controlling iOS Simulators. Gives AI assistants the ability to see, interact with, and debug iOS apps — taking screenshots, tapping elements, reading the UI tree, and automating testing workflows.

Built with native touch injection and native UI tree reading for accurate, reliable automation that doesn't interfere with your machine.

npm Package | GitHub | Issues

Why This Server

Most iOS Simulator MCP servers work by sending mouse clicks to the Simulator window through macOS, then reading the Simulator's window frame through the macOS Accessibility API. This means:

• Your mouse gets hijacked every time the AI taps something
• The Simulator window must stay in the foreground — you can't use your Mac while tests run
• The UI tree returns Simulator chrome (window buttons, toolbar) mixed with actual app elements
• macOS Accessibility permissions are required for your terminal
• Touch coordinates are fragile — they depend on window position and scale

This server takes a different approach:

• Native touch injection via IndigoHID — sends touch events directly to the Simulator's HID system. Sub-pixel accuracy, no mouse movement, works with the Simulator in the background.
• Native UI tree via AXPTranslation — reads the actual iOS accessibility tree through CoreSimulator, not the macOS window. Returns only app elements with correct device-point coordinates.
• No macOS Accessibility permissions needed — everything goes through Apple's Simulator frameworks.
• No window focus required — the Simulator can be minimized or behind other windows.

Features

• 31 tools for complete iOS Simulator control
• Native touch injection — tap, swipe, long press, double tap, multi-tap via IndigoHID (compiled from source on first use)
• Native UI tree — real iOS accessibility tree via AXPTranslation (no Simulator chrome, no macOS AX permissions)
• Screenshot capture with intelligent compression (Sharp-based, max 1280px)
• Element targeting — find and tap elements by identifier, label, or value
• App lifecycle — install apps, launch, terminate, uninstall
• Log integration — filter by bundle ID, log level, or timestamp
• Device management — list simulators, boot/shutdown, get device info
• Compound actions — tap_and_wait combines tap + settle + UI tree in one round trip
• iOS-specific tools — push notifications, permissions, URL schemes, status bar overrides
• Multi-device support — target specific simulators by UDID
• Zero app modifications — works with any iOS app, no SDK integration needed

Prerequisites

• macOS (required for iOS Simulator)
• Xcode with command line tools (xcode-select --install)
• Node.js 18+
• A booted iOS Simulator

That's it. No Accessibility permissions, no special configuration.

Setup

claude mcp add --scope user ios -- npx -y ios-mcp-server

This registers the server globally so it's available in all projects. Use --scope project instead to limit it to the current project.

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Add to your VS Code settings (.vscode/settings.json):

{
  "mcp": {
    "servers": {
      "ios": {
        "command": "npx",
        "args": ["-y", "ios-mcp-server"]
      }
    }
  }
}

Add to your Cursor MCP config (~/.cursor/mcp.json):

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

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

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

Add to your project's .mcp.json (checked into version control so your team gets it too):

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

git clone https://github.com/martingeidobler/ios-mcp-server.git
cd ios-mcp-server
npm install
npm run build
claude mcp add --scope user ios -- node /path/to/ios-mcp-server/dist/index.js

Available Tools

Device Management

| Tool | Description | |------|-------------| | list_devices | List available iOS Simulators and their state | | list_simulators | List available simulator device types (iPhone, iPad models) | | boot_simulator | Boot a simulator by name or UDID (waits up to 60s) |

Screenshot & UI Analysis

| Tool | Description | |------|-------------| | screenshot | Take screenshot for visual analysis. Optional save_path to save to disk | | get_ui_tree | Get UI element hierarchy with bounds, labels, identifiers, and state |

Interaction

| Tool | Description | |------|-------------| | tap | Tap at screen coordinates (device points) | | tap_element | Tap element by identifier, label, or value | | tap_and_wait | Tap element, wait for UI to settle, return new UI tree — single round trip | | long_press | Long press at coordinates (context menus, drag handles) | | double_tap | Double tap at coordinates (zoom in, double-tap interactions) | | multi_tap | Tap N times at coordinates with configurable interval | | tap_sequence | Execute a sequence of steps: tap, long press, swipe, type, key press, and pause | | type_text | Type text into focused input | | press_key | Press key (home, lock, enter, tab, delete, arrows, volume, shake, rotate) | | swipe | Swipe gesture between coordinates | | scroll_to_element | Scroll until element is visible | | wait_for_element | Wait for element to appear (with timeout) |

App Management

| Tool | Description | |------|-------------| | launch_app | Launch app by bundle ID | | terminate_app | Terminate a running app | | install_app | Install .app bundle | | uninstall_app | Uninstall app by bundle ID | | get_current_app | Get foreground app info | | simctl_run | Run a command inside the Simulator |

Diagnostics

| Tool | Description | |------|-------------| | get_logs | Get log output, filterable by bundle ID, log level, and time | | clear_logs | Set log baseline (call before reproducing a bug for clean output) | | get_device_info | Get name, model, iOS version, screen size | | pull_file | Pull a file from an app's container |

iOS-Specific Utilities

| Tool | Description | |------|-------------| | open_url | Open a URL or deep link in the Simulator | | send_push | Send a push notification to an app | | set_permission | Grant, revoke, or reset app permissions | | set_status_bar | Override status bar display (time, battery, signal) |

Example Workflows

Bug documentation

"Clear the logs, launch com.example.app, navigate to the settings screen, tap Save, then show me the logs and a screenshot"

Claude will: clear_logs → launch_app → tap_element → get_logs(bundle_id="com.example.app", level="error") → screenshot(save_path="./bugs/settings-crash.png")

UI testing

"Navigate through the login flow and verify each screen matches the designs"

Claude will use screenshot + get_ui_tree to see and understand each screen, tap_element/type_text to interact, and its vision capabilities to compare against mockups or descriptions.

Smoke testing

"Install the app, launch it, and tap through the main screens to check nothing crashes"

Claude will: install_app → launch_app → navigate with tap_element → get_logs(level="error") to check for errors after each screen.

Deep linking

"Open the deep link myapp://profile/123 and verify the profile screen loads"

Claude will: open_url(url="myapp://profile/123") → get_ui_tree to verify the profile screen elements → screenshot for visual confirmation.

Push notification testing

"Send a push notification to the app and verify the notification appears"

Claude will: send_push(bundle_id="com.example.app", title="Hello", body="Test notification") → screenshot to see the notification.

Demos & Prompting Guide

• PROMPTING.md — best practices, performance tips, and common pitfalls

How It Works

The server communicates over stdio using the Model Context Protocol. Under the hood it uses three mechanisms:

1. xcrun simctl — device management, app lifecycle, screenshots, logs, and simulator commands
2. Native simtouch binary — compiled from Objective-C on first use, sends touch events directly to the Simulator's HID system via IndigoHID/CoreSimulator private frameworks. No mouse involvement.
3. Native simtree binary — compiled from Objective-C on first use, reads the iOS app's accessibility tree via AXPTranslation/CoreSimulator. Returns real iOS element data, not macOS Simulator window chrome.

Both native binaries are compiled automatically on first use and cached. The source files (native/simtouch.m, native/simtree.m) ship with the package; only Xcode command line tools are needed.

Architecture

MCP Client (Claude Code, Desktop, VS Code, etc.)
    ↕ stdio (MCP protocol)
iOS MCP Server (Node.js)
    ↕               ↕                  ↕
xcrun simctl     simtouch            simtree
    ↕               ↕                  ↕
iOS Simulator    IndigoHID          AXPTranslation
                 (CoreSimulator)    (CoreSimulator)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE.