expo-mcp

MCP server for Expo/React Native app automation with Maestro integration.

Features

• Session-Based Architecture: start_session launches Expo, binds a device, and acquires a lease — no manual device ID management

• Device Lease with TTL: 2-minute lease auto-renewed on every device tool call; expires after inactivity so other instances can use the device

• Cross-Instance Coordination: Multiple MCP instances can run simultaneously without device conflicts

• Expo Dev Server Management: Start/stop/reload Expo development server

• Maestro Integration: Full UI automation tools (tap, input, screenshot, etc.)

Installation

As a Claude Code Plugin (Recommended)

Install as a plugin to get the MCP server, QA agent, flow writer, and usage guide in one step:

# 1. Add the marketplace source
/plugin marketplace add DaveDev42/expo-mcp

# 2. Install the plugin
/plugin install expo-mcp --scope project

Or from the terminal:

claude plugin marketplace add DaveDev42/expo-mcp
claude plugin install expo-mcp --scope project

This automatically:

• Configures the expo MCP server (no manual .mcp.json needed)

• Adds a QA agent (qa) for automated mobile app testing

• Adds a flow writer agent (flow-writer) for creating Maestro YAML test flows

• Adds a usage guide skill (/expo-guide) with tool reference and best practices

• Adds a validation hook that warns on QA PASS verdicts without execution evidence

As an MCP Server Only

npx -y expo-mcp

With pnpm:

pnpx expo-mcp

Usage with Claude Code

Manual MCP Setup

If not using the plugin, add to your .mcp.json:

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

Monorepo Setup

Use a positional argument to specify the app directory:

{
  "mcpServers": {
    "expo-mcp": {
      "command": "npx",
      "args": ["-y", "expo-mcp", "apps/mobile"]
    }
  }
}

Specific Device

Pin a specific simulator or emulator with --device-id:

{
  "mcpServers": {
    "expo-mcp": {
      "command": "npx",
      "args": ["-y", "expo-mcp", "--device-id=6D192F60-1234-5678-ABCD-000000000000"]
    }
  }
}

Tool Filtering

Exclude specific tools with --exclude-tools:

{
  "mcpServers": {
    "expo-mcp": {
      "command": "npx",
      "args": ["-y", "expo-mcp", "apps/mobile", "--exclude-tools=list_devices"]
    }
  }
}

Or expose only specific tools with --tools:

{
  "mcpServers": {
    "expo-mcp": {
      "command": "npx",
      "args": ["-y", "expo-mcp", "--tools=start_session,stop_session,take_screenshot"]
    }
  }
}

CLI Reference

Usage: expo-mcp [app-dir] [options]

Arguments:
  app-dir                      Path to Expo app directory (default: cwd)

Options:
  --device-id=<id>             Specific device to use (iOS simulator UUID or Android serial)
  --exclude-tools=tool1,tool2  Exclude specific tools from the MCP server
  --tools=tool1,tool2          Only expose specific tools
  -h, --help                   Show help message
  -v, --version                Show version number

Quick Start

# 1. Start session (launches Expo + binds device + acquires lease)
start_session({ target: "ios-simulator" })

# 2. Use tools directly (no device_id needed!)
take_screenshot()
tap_on({ text: "Login" })
input_text({ text: "hello@example.com" })
press_key({ key: "Enter" })
scroll({ direction: "down" })
swipe({ direction: "left" })

# 3. Run Maestro flows
run_maestro_flow({ flow_yaml: "- assertVisible: Welcome" })
check_maestro_flow_syntax({ flow_yaml: "- tap: Login" })

# 4. Reload app after code changes
reload_app()

# 5. Check logs if needed
get_logs({ level: "error" })

# 6. Stop session when done
stop_session()

Plugin Features

When installed as a Claude Code plugin, you get these additional features:

QA Agent

Delegate mobile QA testing to the qa agent. It systematically tests your app on a simulator/emulator with strict evidence requirements — no code-review-only verdicts.

# In Claude Code, delegate to the QA agent:
"Test the login flow on iOS simulator"  →  delegates to qa agent

The agent follows a structured methodology: launch app → inspect UI → interact → verify → report with PASS/FAIL/INCONCLUSIVE verdict.

Flow Writer Agent

The flow-writer agent inspects the live app and creates Maestro YAML test flows:

# Ask the flow writer to create a test flow:
"Write a Maestro flow for the onboarding sequence"  →  delegates to flow-writer agent

It validates syntax, executes the flow to verify it works, and writes the .yaml file to your project.

Usage Guide

Access the tool reference and best practices with /expo-guide:

/expo-guide                    # Full guide
/expo-guide session            # Session lifecycle
/expo-guide debugging          # Debugging tips

Tools

Lifecycle Tools

start_session Options

Maestro Tools

All Maestro tools work automatically once a session is active — device_id is injected from the session:

Note: Device tools require an active session. Call start_session first. list_devices and check_maestro_flow_syntax can be called anytime.

Device Lease System

The device lease prevents one MCP instance from holding a device indefinitely:

1. Acquire: start_session acquires a 2-minute device lease

2. Auto-Renew: Every device tool call (take_screenshot, tap_on, etc.) resets the 2-minute timer

3. Expire: If no device tool is called for 2 minutes, the lease expires and the device becomes available

4. Re-acquire: Call start_session again to re-acquire (server stays running, no restart needed)

5. Check: get_session_status shows remaining lease time

Multiple MCP instances coordinate via a file-based registry (/tmp/expo-mcp/instances/), so two instances cannot claim the same device simultaneously.

Environment Variables

How It Works

1. Session Start: start_session starts Expo dev server, waits for device connection, and acquires a lease

2. Device Binding: Connected device ID is stored in the session with a 2-minute TTL

3. Automatic Injection: All Maestro device tools automatically use the session's device ID

4. Lease Renewal: Every device tool call resets the lease timer

5. Session End: stop_session cleans up everything, or the lease expires after inactivity

Non-Interactive Environments (CI/CD, AI Agents)

This MCP server automatically enables --offline mode when running in CI environments (CI=1). This allows the app to work without requiring an EXPO_TOKEN.

What Offline Mode Does

• Skips Expo server communication (manifest signing)

• Does NOT affect your app's network features (API calls, fetch, etc.)

• Tunnel mode (--tunnel) is not available in offline mode

If You Need Expo Account Features

For features requiring Expo authentication, disable offline mode and provide EXPO_TOKEN:

{
  "mcpServers": {
    "expo-mcp": {
      "env": {
        "EXPO_TOKEN": "your-token-here"
      }
    }
  }
}

Then call start_session with offline: false:

start_session({ target: "ios-simulator", offline: false })

Requirements

• Node.js >= 18

• Xcode (for iOS Simulator)

• Android Studio (for Android Emulator)

• Maestro CLI (for UI automation)

License

MIT