expo-mcp

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