expo-mcp

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

Features

• Session-Based Architecture: Launch Expo and device binds automatically - no manual device ID management
• Expo Dev Server Management: Start/stop/reload Expo development server
• Maestro Integration: Full UI automation tools (tap, input, screenshot, etc.)

Installation

npm install -g expo-mcp
# or
npx expo-mcp

Usage with Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "expo-mcp": {
      "command": "npx",
      "args": ["-y", "expo-mcp"],
      "env": {
        "EXPO_APP_DIR": "/path/to/your/expo/app"
      }
    }
  }
}

Quick Start

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

# 2. Use Maestro tools directly (no device_id needed!)
take_screenshot()
tap_on({ text: "Login" })
input_text({ text: "hello@example.com" })

# 3. Reload app after code changes
reload_expo()

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

# 5. Stop session when done
stop_expo()

Tools

Lifecycle Tools

Tool	Description
app_status	Get session status (server info, device_id)
launch_expo	Start Expo server and establish session with device
stop_expo	Stop Expo server and end session
reload_expo	Hot reload the app on connected device
get_logs	Get Metro bundler logs (filterable by level)

launch_expo Options

Option	Type	Description
target	ios-simulator | android-emulator | web-browser	Device to launch
host	lan | tunnel | localhost	Connection mode
port	number	Server port (default: 8081, auto-increments if busy)
clear	boolean	Clear Metro bundler cache
dev	boolean	Development mode (default: true)

Maestro Tools

All Maestro tools work automatically once a session is active:

Tool	Description
tap_on	Tap on UI element by text, id, or point
input_text	Type text into focused field
take_screenshot	Capture screen (auto-resized for LLM)
inspect_view_hierarchy	Get UI element tree
launch_app	Launch app by bundle ID
back	Press back button
run_flow	Run Maestro YAML flow

Note: Maestro tools require an active session. Call launch_expo first.

Environment Variables

Variable	Description	Default
EXPO_APP_DIR	Path to Expo app directory	Current working directory
MAESTRO_CLI_PATH	Path to Maestro CLI	~/.maestro/bin/maestro
ESSENTIAL_TOOLS	Comma-separated list of tools to expose	All tools
LOG_BUFFER_SIZE	Max log lines to keep in memory	400

How It Works

1. Session Creation: launch_expo starts Expo dev server and waits for device connection
2. Device Binding: Once device connects, its ID is stored in the session
3. Automatic Injection: All Maestro tools automatically use the session's device ID
4. Session End: stop_expo cleans up everything

This eliminates the need for manual device_id management.

Requirements

• Node.js >= 18
• Xcode (for iOS Simulator)
• Android Studio (for Android Emulator)
• Maestro CLI (for UI automation)

License

MIT