Expo iOS Development

You can use this MCP server to orchestrate iOS simulators, Expo/Metro, and Detox UI automation from one unified control plane. It lets you boot and manage simulators, run the Expo development server, execute Detox actions, capture visuals, stream logs, and perform reliable, retryable operations all from your LLM-enabled workflows.

How to use

You interact with the MCP server through an MCP client integrated into your preferred LLM tool. Start by configuring a local MCP client that points to the exposed stdio MCP endpoints described below. Once configured, you can command the server to boot simulators, start Expo, initialize Detox, perform UI actions, capture screenshots and videos, and run visual regression checks. The server maintains a state machine to coordinate simulator, Expo, and Detox, ensuring operations don’t conflict and retries are attempted automatically for transient failures.

How to install

Prerequisites you must meet before running the MCP server include: macOS with Xcode and Command Line Tools, Node.js 18 or newer (20+ recommended), an available iOS Simulator, and an Expo/React Native project configured with Detox for UI automation.

Step-by-step setup to get started locally:

1. Install dependencies for your development environment.

2. Create the MCP configuration file at your project root and tailor paths to your environment.

3. Run the MCP server using your chosen MCP client configuration. You will typically start with a development build and then a live run for testing.

Configuration

The server is configured via an MCP JSON file that defines where your project resides, where artifacts go, and how to start Expo/Detox workflows. You specify the project path, artifacts location, default device, and Detox configuration used for UI automation.

{
  "projectPath": "/path/to/your/expo-app",
  "artifactsRoot": "./artifacts",
  "defaultDeviceName": "iPhone 15",
  "detox": {
    "configuration": "ios.sim.debug"
  }
}

MCP client configurations

Two example MCP client configurations show how to connect your LLM tools to the local MCP server using stdio. Use the same command and environment details in your client setup.

{
  "mcpServers": {
    "expo_ios_detox": {
      "command": "node",
      "args": ["/path/to/expo_ios_development_mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG": "/path/to/mcp.config.json"
      }
    }
  }
}

Continued client configuration

A second client example uses the same server entry but in a different client format. This demonstrates how a Cursor-like stdio client would launch the same MCP server process.

{
  "servers": {
    "expo_ios_detox": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/expo_ios_development_mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG": "/path/to/mcp.config.json"
      }
    }
  }
}

Security and environment

Keep MCP_CONFIG and other sensitive paths secure. Do not expose internal paths in public prompts. Use environment-specific overrides for development, staging, and production to avoid leaking credentials or internal project structure.

Troubleshooting

If you encounter issues, check simulator and Expo logs, verify Detox readiness, and ensure the MCP server is in the correct state before issuing UI commands. Use the visual regression and log streaming features to collect evidence during debugging.

Notes on tools and flows

This MCP server provides a rich set of capabilities to control iOS simulators, Expo/Metro, Detox actions, and visual checks. You can run sequences of actions with Flow-like prompts, capture evidence, and compare against baselines to maintain UI consistency across changes.

Available tools

simulator.list_devices

List all available iOS simulators

simulator.boot

Boot a simulator device

simulator.shutdown

Shut down a simulator

simulator.erase

Factory reset a simulator

simulator.screenshot

Take a screenshot of the current simulator view

simulator.record_video.start

Start recording a video of simulator activity

simulator.record_video.stop

Stop video recording on the simulator

simulator.log_stream.start

Start streaming real-time simulator logs

simulator.log_stream.stop

Stop log streaming from the simulator

expo.start

Start the Expo/Metro server for your app

expo.stop

Stop the Expo/Metro server

expo.status

Get the current Expo/Metro status and bundle URL

expo.logs.tail

Tail recent Expo logs for debugging

expo.reload

Reload the app in Expo to pick up changes

detox.session.start

Initialize a Detox session for UI automation

detox.session.stop

Terminate the Detox session

detox.healthcheck

Verify Detox is ready for UI automation

ui.tap

Tap an element (by testID, text, or label) in the app under test

ui.long_press

Long press an element to trigger context menus or actions

ui.type

Type text into an input field

ui.swipe

Perform swipe gestures on elements or screens

ui.scroll

Scroll within scrollable views in the app under test

ui.press_key

Press a keyboard key within the app context

ui.wait_for

Wait for an element to become visible or actionable

ui.assert_text

Assert that a UI element contains the expected text

ui.assert_visible

Assert that a UI element is visible on screen

visual.baseline.save

Save a baseline screenshot for future comparisons

visual.baseline.list

List saved baseline images for reference

visual.baseline.delete

Delete a saved baseline image

visual.compare

Compare the current screenshot against a saved baseline using pixel-perfect diff

visual.compare_to_design

Compare current view against a pasted design image (e.g., Figma) for visual alignment

flow.run

Execute a predefined sequence of MCP tool calls as a flow