What can you do with this server?

The Expo iOS Development MCP Server enables AI models to programmatically control iOS simulators, manage Expo/Metro development servers, and perform comprehensive UI automation and testing for Expo/React Native applications. Simulator Management: List, boot, shutdown, and erase iOS simulator devices; capture screenshots with custom naming; record videos; stream real-time system logs. Expo/Metro Control: Start/stop development server with optional cache clearing; check status and get bundle information; reload app; tail recent logs with configurable line count. UI Automation (via Detox): Initialize and manage Detox sessions with health checks and session reuse; perform tap, long press, type, swipe, scroll, and key press actions; wait for elements with timeout control; assert element text and visibility; select elements by testID, text, or label. Testing Workflows: Parse and run acceptance criteria from markdown files; execute test flows; perform visual regression testing with baseline screenshots and pixelmatch comparison; compare against design mockups (e.g., Figma); report missing testIDs for improved testability. Flow Orchestration: Execute multi-step sequences of tool calls as macros with configurable error handling; chain actions for complex test scenarios; stop on error or continue through failures. Debugging & Monitoring: Collect evidence for bugs; access real-time logs from simulator, Expo, and Detox; retrieve current server state; features concurrency control with lock manager and automatic retry with backoff for robustness.

Which integrations are available for this server?

Enables control of Expo development server and Metro bundler, including starting/stopping the server, checking status, tailing logs, and reloading the app. Provides comprehensive control over iOS Simulator including booting/shutting down devices, factory resets, screenshot capture, video recording, log streaming, and UI automation via Detox for testing Expo/React Native applications. Enables control of Metro bundler for React Native development, including server management and app reloading capabilities.

How do I use Expo iOS Development MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Expo iOS Development MCP Server boot the iPhone 15 simulator and take a screenshot" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Expo iOS Development MCP Server

An MCP (Model Context Protocol) server that enables LLM tools like Claude Code, Cursor, and Codex to control iOS Simulator, Expo/Metro, and run UI automation via Detox.

Features

Simulator Control: Boot, shutdown, erase simulators via simctl
Screenshots & Video: Capture screenshots and record videos
Log Streaming: Real-time simulator log capture with ring buffer
Expo/Metro: Start/stop Expo development server
UI Automation: Execute Detox actions (tap, swipe, type, wait, assert)
Visual Regression: Screenshot comparison with pixelmatch
Acceptance Criteria Testing: Parse markdown criteria, run automated tests, report missing testIDs
Concurrency Control: Lock manager prevents conflicting operations
Retry with Backoff: Automatic retry for transient failures

Prerequisites

macOS with Xcode and Command Line Tools
Node.js 18+ (20+ recommended)
iOS Simulator available
An Expo/React Native project with Detox configured (for UI automation)

Quick Start

# Install dependencies pnpm install # Verify environment pnpm verify # Build TypeScript pnpm build # Run in development mode pnpm dev

Configuration

Create mcp.config.json in the project root (see mcp.config.example.json):

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

MCP Client Configuration

Claude Code

Add to your Claude Code MCP settings:

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

Cursor

Add to ~/.cursor/mcp.json:

{ "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" } } } }

Available Tools

Simulator

Tool	Description
`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
`simulator.record_video.start`	Start video recording
`simulator.record_video.stop`	Stop video recording
`simulator.log_stream.start`	Start log streaming
`simulator.log_stream.stop`	Stop log streaming

Expo

Tool	Description
`expo.start`	Start Expo/Metro server
`expo.stop`	Stop Expo/Metro server
`expo.status`	Get Expo/Metro status
`expo.logs.tail`	Get recent Expo logs
`expo.reload`	Reload the app

Detox Session

Tool	Description
`detox.session.start`	Initialize Detox session
`detox.session.stop`	Terminate Detox session
`detox.healthcheck`	Verify Detox is ready

UI Automation

Tool	Description
`ui.tap`	Tap an element
`ui.long_press`	Long press an element
`ui.type`	Type text into an input
`ui.swipe`	Swipe gesture
`ui.scroll`	Scroll in a direction
`ui.press_key`	Press a keyboard key
`ui.wait_for`	Wait for element visibility
`ui.assert_text`	Assert element text content
`ui.assert_visible`	Assert element is visible

Visual Regression

Tool	Description
`visual.baseline.save`	Save baseline screenshot
`visual.baseline.list`	List saved baselines
`visual.baseline.delete`	Delete a baseline
`visual.compare`	Compare against baseline (uses pixelmatch)
`visual.compare_to_design`	Compare simulator screenshot against pasted Figma/design image

Acceptance Criteria Testing

Tool	Description
`acceptance.parse`	Parse acceptance criteria markdown file into structured data
`acceptance.run`	Run all acceptance tests with comprehensive reporting
`acceptance.run_flow`	Execute a specific test flow by name
`acceptance.check`	Check a single criterion by ID or description match

Flow

Tool	Description
`flow.run`	Execute a sequence of tool calls

Prompt Templates

The server provides discoverable prompt templates for common workflows:

Prompt	Description
`repro_and_collect_evidence`	Reproduce a bug and collect evidence
`ui_regression_check`	Perform visual regression testing
`test_user_flow`	Test a complete user flow
`debug_app_crash`	Debug an app crash
`setup_test_session`	Set up a fresh test session

Resources

The server exposes these MCP resources:

resource://state - Current server state (simulator, expo, detox)
resource://logs/simulator/latest - Recent simulator logs
resource://logs/expo/latest - Recent Expo logs
resource://logs/detox/latest - Recent Detox logs
resource://artifacts/latest - Artifact manifest

Usage Guide

Getting Started

Once the MCP server is configured in your LLM client (Claude Code, Cursor, etc.), you can interact with it using natural language. The LLM will automatically invoke the appropriate tools.

Step 1: Set Up Your Development Session

Before running UI automation, you need to:

Boot the simulator - Start an iOS Simulator device
Start Expo - Launch the Metro bundler and load your app
Initialize Detox - Set up the Detox session for UI automation

Step 2: Develop and Test

With the session ready, you can:

Run UI interactions (tap, type, swipe)
Take screenshots at any point
Assert element states and text content
Record videos of interactions
Perform visual regression tests

Step 3: Debug Issues

When something goes wrong:

Check logs from Expo/Metro and simulator
Take screenshots to see current state
Use the debug prompts to investigate crashes

Example Prompts

Here are example prompts you can use with Claude Code, Cursor, or other MCP-enabled LLM tools during Expo app development:

Session Setup

Boot the iPhone 15 Pro simulator and start my Expo app

Set up a fresh test session - boot the simulator, start Expo, and initialize Detox

List all available iOS simulators and tell me which ones are booted

Taking Screenshots

Take a screenshot of the current screen and save it as "home-screen"

Take a screenshot after each step of the login flow

Start recording a video, then stop it after I tell you the flow is complete

Tap the "Login" button on the home screen

Navigate to the Settings screen by tapping the settings icon (testID: settings-tab)

Scroll down on the main feed until you see the "Load More" button

UI Automation - Forms

Fill in the login form: - Email: test@example.com - Password: password123 Then tap the Submit button

Type "Hello World" into the search input (testID: search-input) and wait for results to appear

Clear the text in the email field and type a new email address

UI Automation - Gestures

Swipe left on the first item in the list to reveal delete button

Swipe down to refresh the feed and wait for new content to load

Long press on the profile picture to open the context menu

Assertions and Verification

Verify that the welcome message shows "Hello, John!"

Wait for the loading spinner to disappear and then check if the data loaded correctly

Assert that the error message "Invalid credentials" is visible after failed login

Visual Regression Testing

Save a baseline screenshot of the login screen for visual regression testing

Compare the current settings page against the baseline and tell me if there are any visual differences

Run visual regression on all saved baselines and report any failures

Design Comparison (Figma to Implementation)

The MCP server supports comparing Figma design screenshots directly against the iOS Simulator. Simply copy and paste a Figma screenshot into your prompt!

Here's the Figma design for the login screen. [paste screenshot] Compare the current simulator view against this design and tell me the differences.

I've pasted the design mockup for the settings page. [paste screenshot] Check if my implementation matches and list what needs to be fixed.

[paste Figma screenshot] This is the target design. Please compare it against the simulator and fix any visual differences in the code.

Compare this design against my current implementation: [paste screenshot] Focus on the header section only (use region comparison).

Acceptance Criteria Testing

The acceptance criteria testing system allows you to write human-readable acceptance criteria in markdown and have them automatically tested against your app.

Writing Acceptance Criteria Files

Create a markdown file with checkbox items organized into sections:

# Login Screen Acceptance Criteria ## Visual Elements - [ ] App logo is visible at the top of the screen - [ ] Email input field is visible with placeholder "Enter email" - [ ] Password input field is visible with placeholder "Enter password" - [ ] "Sign In" button is visible and has text "Sign In" ## Interactions - [ ] Tapping email field focuses the input - [ ] Tapping "Sign In" button with valid credentials navigates to home screen - [ ] Tapping "Forgot Password" link opens password reset modal ## Test Flows ### Happy Path Login 1. Wait for element `login-screen` to be visible 2. Type "test@example.com" into `email-input` 3. Type "password123" into `password-input` 4. Tap `sign-in-button` 5. Wait for element `home-screen` to be visible

Parsing Acceptance Criteria

Parse the acceptance criteria file at /path/to/login-criteria.md

Parse this acceptance criteria and tell me how many testable items there are: [paste markdown content]

Running Acceptance Tests

Run the acceptance criteria tests from /path/to/login-criteria.md

Run acceptance tests for the login screen and generate a report

Execute only the "Visual Elements" section from the acceptance criteria

Running Specific Test Flows

Run the "Happy Path Login" test flow from the acceptance criteria file

Execute the signup flow from acceptance-criteria.md and take screenshots at each step

Checking Individual Criteria

Check if the criterion "App logo is visible" passes

Verify the single criterion with ID "visual-1" from the acceptance file

Understanding Test Results

The acceptance criteria runner produces detailed reports with:

Pass: Criterion was verified successfully
Fail: Criterion check failed (element not found, assertion failed)
Blocked: Cannot test because required testIDs are missing

When tests are blocked, the report includes a "Missing Requirements" section:

## Missing Requirements for Testability | Element | Suggested testID | Type | Reason | |---------|-----------------|------|--------| | App logo | `app-logo` | testID | Required for "App logo is visible" | | Sign In button | `sign-in-button` | testID | Required for "Tapping Sign In button" |

This helps developers add the necessary testIDs to make criteria testable.

Debugging and Logs

Show me the last 100 lines of Expo logs - I'm seeing a crash

The app crashed after tapping the submit button. Collect evidence: take a screenshot, get the logs, and help me debug what went wrong

Start streaming simulator logs so we can monitor for errors during testing

Complex Flows

Test the complete signup flow: 1. Tap "Create Account" 2. Fill in name, email, password 3. Accept terms and conditions 4. Tap "Sign Up" 5. Verify the welcome screen appears Take screenshots at each step

Run through the checkout flow and compare each screen against baselines: 1. Add item to cart 2. Go to cart 3. Proceed to checkout 4. Enter shipping info 5. Confirm order

Reproduce bug #123: The app crashes when tapping the profile button while on the settings page. Collect all evidence including screenshots and logs.

Using Flow Runner

Execute this test flow: - Wait for element "welcome-screen" - Tap "get-started-button" - Wait for element "onboarding-step-1" - Swipe left - Wait for element "onboarding-step-2" - Swipe left - Tap "finish-button"

Expo Development

Check the status of Metro - is it running and what's the bundle URL?

Reload the app to pick up my latest code changes

Stop Expo, clear the cache, and restart it fresh

Cleanup

Stop the Detox session and shut down the simulator

Erase the simulator to start with a clean slate

Common Workflows

Workflow 1: Daily Development Cycle

1. "Boot iPhone 15 and start Expo for my app" 2. Make code changes... 3. "Reload the app" 4. "Take a screenshot of the updated UI" 5. "Tap the new button I added and verify it works" 6. Repeat...

Workflow 2: Bug Reproduction

1. "Set up a test session with iPhone 15 Pro" 2. "Start recording a video" 3. "Navigate to the screen where the bug occurs" 4. "Perform the actions that trigger the bug" 5. "Stop recording and collect logs" 6. "Take a final screenshot and summarize what happened"

Workflow 3: Visual Regression Suite

1. "Boot simulator and start Expo" 2. "Initialize Detox session" 3. "List all saved baselines" 4. "Compare each major screen against its baseline" 5. "Generate a report of any visual differences"

Workflow 4: End-to-End Testing

1. "Set up fresh test session - erase simulator first for clean state" 2. "Run the complete user registration flow with test data" 3. "Verify the user lands on the dashboard" 4. "Save baseline screenshots for key screens" 5. "Stop session and generate test summary"

Workflow 5: Design-Driven Development

1. Copy a Figma design screenshot 2. "Boot simulator and start Expo" 3. Paste the design: "Implement this login screen design: [paste]" 4. Claude Code implements the UI components 5. "Compare my implementation against the design" 6. Review the diff overlay and feedback 7. "Fix the spacing issues shown in the comparison" 8. Repeat comparison until design match is satisfactory

Workflow 6: Acceptance Criteria Testing

1. Write acceptance criteria in markdown (login-criteria.md) 2. "Boot simulator and start Expo" 3. "Initialize Detox session" 4. "Parse the acceptance criteria file at login-criteria.md" 5. "Run all acceptance tests and generate a report" 6. Review the report - fix any failing tests 7. Add missing testIDs reported in the "Missing Requirements" section 8. "Re-run the acceptance tests" 9. Repeat until all criteria pass

Workflow 7: Continuous Acceptance Testing During Development

1. "Set up test session with iPhone 15" 2. Make code changes to your app... 3. "Reload the app" 4. "Run the acceptance criteria for the feature I'm working on" 5. Review pass/fail/blocked status 6. Fix issues and add missing testIDs 7. Repeat steps 2-6 until acceptance criteria pass

Tips for Effective Prompts

Use testIDs: Reference elements by their testID prop for reliable targeting
Tap the button with testID "submit-button"
Be specific about selectors: Specify whether you're using id, text, or label
Tap the element with text "Continue" (not the testID)
Chain actions clearly: Break complex flows into clear steps
First wait for the login screen, then fill the form, then tap submit
Request evidence: Ask for screenshots and logs when debugging
Take a screenshot before and after tapping the button
Use flow.run for sequences: For repeatable test flows, use the flow runner
Execute this as a flow: tap login, type email, type password, tap submit
Write acceptance criteria in markdown: Use checkbox format for testable criteria
- [ ] Button with testID "submit-btn" is visible - [ ] Tapping "Login" navigates to home screen
Include test flows in acceptance criteria: Define step-by-step flows under ## Test Flows
### Login Flow 1. Type "user@example.com" into `email-input` 2. Tap `submit-button`

Development

# Run with hot reload pnpm dev # Build for production pnpm build # Run production build pnpm start # Enable debug logging MCP_DEBUG=true pnpm dev

Architecture

The server is organized into modular subsystems:

src/ index.ts # MCP stdio entrypoint config/ # Configuration loading and validation core/ # State machine, errors, logger, artifacts, lock, retry mcp/ # MCP server, schemas, prompt templates simulator/ # simctl wrapper (devices, screenshots, video, logs) expo/ # Expo/Metro control (start, stop, logs, flow runner) detox/ # Detox micro-test runner (actions, selectors, output parsing) visual/ # Visual regression (baseline management, pixelmatch diff) acceptance/ # Acceptance criteria testing (parser, mapper, checker, reporter)

Key Patterns

State Machine: Tracks simulator, Expo, and Detox states; UI commands require simulator.booted + detox.ready
Detox Micro-Tests: UI actions generate temporary Jest tests, run via Detox CLI, parse [MCP_RESULT] markers
Error Taxonomy: LLM-friendly error codes with auto-populated remediation hints
Ring Buffer Logging: Per-source log retention (20,000 entries each)

Code Metrics

Metric	Value
Total Files	41
Total Lines	8,574
Avg Complexity	12.9
Code Consistency	99%
Circular Deps	0

Documentation

Architecture Documentation - Detailed technical architecture with diagrams
Implementation Plan - Full implementation document with code examples

Author

Andrea Salvatore andreahaku@gmail.com

License

MIT

Expo iOS Development MCP Server

Features

Prerequisites

Quick Start

Configuration

MCP Client Configuration

Claude Code

Cursor

Available Tools

Simulator

Expo

Detox Session

UI Automation

Visual Regression

Acceptance Criteria Testing

Flow

Prompt Templates

Resources

Usage Guide

Getting Started

Step 1: Set Up Your Development Session

Step 2: Develop and Test

Step 3: Debug Issues

Example Prompts

Session Setup

Taking Screenshots

UI Automation - Navigation

UI Automation - Forms

UI Automation - Gestures

Assertions and Verification

Visual Regression Testing

Design Comparison (Figma to Implementation)

Acceptance Criteria Testing

Writing Acceptance Criteria Files

Parsing Acceptance Criteria

Running Acceptance Tests

Running Specific Test Flows

Checking Individual Criteria

Understanding Test Results

Debugging and Logs

Complex Flows

Using Flow Runner

Expo Development

Cleanup

Common Workflows

Workflow 1: Daily Development Cycle

Workflow 2: Bug Reproduction

Workflow 3: Visual Regression Suite

Workflow 4: End-to-End Testing

Workflow 5: Design-Driven Development

Workflow 6: Acceptance Criteria Testing

Workflow 7: Continuous Acceptance Testing During Development

Tips for Effective Prompts

Development

Architecture

Key Patterns

Code Metrics

Documentation

Author

License

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API