expo-mcp

MCP-Server für die Automatisierung von Expo/React Native-Apps mit Maestro-Integration.

Funktionen

• Sitzungsbasierte Architektur: start_session startet Expo, bindet ein Gerät und erwirbt ein Lease – keine manuelle Geräte-ID-Verwaltung erforderlich

• Geräte-Lease mit TTL: 2-Minuten-Lease, das bei jedem Aufruf eines Gerätetools automatisch verlängert wird; läuft nach Inaktivität ab, damit andere Instanzen das Gerät nutzen können

• Instanzübergreifende Koordination: Mehrere MCP-Instanzen können gleichzeitig ohne Gerätekonflikte ausgeführt werden

• Expo Dev Server Management: Starten/Stoppen/Neuladen des Expo-Entwicklungsservers

• Maestro-Integration: Umfassende UI-Automatisierungstools (Tippen, Eingabe, Screenshot, etc.)

Installation

Als Claude Code Plugin (Empfohlen)

Zwei Befehle, dann neu starten:

# 1. Install the plugin. Just dismiss the "Expo App Directory" prompt
#    (or leave it empty) — the next step configures it for you.
/plugin marketplace add DaveDev42/expo-mcp
/plugin install expo-mcp --scope project

# 2. One-shot installer. Runs environment checks, auto-detects the Expo
#    app directory, and writes the userConfig directly into
#    .claude/settings.json. No /plugin UI round-trip needed.
/expo-mcp:install                     # auto-detect
/expo-mcp:install apps/mobile         # monorepo: pass the path explicitly

Starten Sie danach Claude Code neu und alle Tools, Agents und Skills sind bereit.

Installer-Flags:

/expo-mcp:install apps/mobile --global        # write to ~/.claude/settings.json
/expo-mcp:install --scaffold-maestro          # also create a starter maestro/
/expo-mcp:install --skip-doctor               # skip prerequisite checks

Der Installer führt gebündelte Node-Skripte (doctor.mjs, detect-app-dir.mjs, scaffold-maestro.mjs) aus dem Plugin-Verzeichnis aus. Claude Code wird Sie beim ersten Ausführen jedes Skripts um Bestätigung bitten – bestätigen Sie diese, um fortzufahren.

Wenn Sie die Skripte lieber vorab bestätigen möchten (ohne Abfragen), fügen Sie dies zu .claude/settings.local.json in Ihrem Projekt hinzu – ersetzen Sie dabei <PATH> durch den absoluten Pfad, den Claude Code beim ersten Ausführen jedes Skripts anzeigt:

{
  "permissions": {
    "allow": [
      "Bash(node <PATH>/doctor.mjs:*)",
      "Bash(node <PATH>/detect-app-dir.mjs:*)",
      "Bash(node <PATH>/scaffold-maestro.mjs:*)"
    ]
  }
}

Die Installation des Plugins richtet automatisch Folgendes ein:

• Den expo MCP-Server (kein manuelles .mcp.json erforderlich)

• Einen QA-Agenten (qa) für automatisiertes Testen mobiler Apps

• Einen Flow-Writer-Agenten (flow-writer) zum Erstellen von Maestro YAML-Test-Flows

• Einen Nutzungsleitfaden-Skill (/expo-guide) mit Tool-Referenz und Best Practices

• Einen Validierungs-Hook, der bei QA-PASS-Urteilen ohne Ausführungsnachweis warnt

Nur als MCP-Server

Dieses Projekt wird nur über GitHub vertrieben (der Name expo-mcp auf npm gehört zu einem anderen, unabhängigen Paket – verwenden Sie es nicht). Führen Sie es über die GitHub-Referenz aus:

npx -y github:DaveDev42/expo-mcp

Verwendung mit Claude Code

Manuelle MCP-Einrichtung

Falls Sie das Plugin nicht verwenden, fügen Sie dies zu Ihrer .mcp.json hinzu:

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

Monorepo-Einrichtung

Verwenden Sie ein Positionsargument, um das App-Verzeichnis anzugeben:

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

Spezifisches Gerät

Fixieren Sie einen bestimmten Simulator oder Emulator mit --device-id:

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

Tool-Filterung

Schließen Sie bestimmte Tools mit --exclude-tools aus:

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

Oder stellen Sie nur bestimmte Tools mit --tools bereit:

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

CLI-Referenz

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

Schnellstart

# 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-Funktionen

Wenn Sie das Plugin als Claude Code-Plugin installieren, erhalten Sie diese zusätzlichen Funktionen:

QA-Agent

Delegieren Sie mobiles QA-Testing an den qa-Agenten. Er testet Ihre App systematisch auf einem Simulator/Emulator mit strengen Nachweisanforderungen – keine Urteile, die nur auf Code-Reviews basieren.

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

Der Agent folgt einer strukturierten Methodik: App starten → UI untersuchen → interagieren → verifizieren → berichten mit PASS/FAIL/INCONCLUSIVE-Urteil.

Flow-Writer-Agent

Der flow-writer-Agent untersucht die Live-App und erstellt 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

Er validiert die Syntax, führt den Flow aus, um sicherzustellen, dass er funktioniert, und schreibt die .yaml-Datei in Ihr Projekt.

Nutzungsleitfaden

Greifen Sie mit /expo-guide auf die Tool-Referenz und Best Practices zu:

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

Tools

Lebenszyklus-Tools

start_session Optionen

Maestro-Tools

Alle Maestro-Tools funktionieren automatisch, sobald eine Sitzung aktiv ist – die device_id wird aus der Sitzung injiziert:

Hinweis: Gerätetools erfordern eine aktive Sitzung. Rufen Sie zuerst start_session auf. list_devices und check_maestro_flow_syntax können jederzeit aufgerufen werden.

Geräte-Lease-System

Das Geräte-Lease verhindert, dass eine MCP-Instanz ein Gerät unbegrenzt belegt:

1. Erwerben: start_session erwirbt ein 2-Minuten-Geräte-Lease

2. Automatische Verlängerung: Jeder Aufruf eines Gerätetools (take_screenshot, tap_on usw.) setzt den 2-Minuten-Timer zurück

3. Ablauf: Wenn 2 Minuten lang kein Gerätetool aufgerufen wird, läuft das Lease ab und das Gerät wird verfügbar

4. Erneutes Erwerben: Rufen Sie start_session erneut auf, um es wieder zu erwerben (Server bleibt aktiv, kein Neustart erforderlich)

5. Prüfung: get_session_status zeigt die verbleibende Lease-Zeit an

Mehrere MCP-Instanzen koordinieren sich über eine dateibasierte Registrierung (/tmp/expo-mcp/instances/), sodass zwei Instanzen nicht gleichzeitig dasselbe Gerät beanspruchen können.

Umgebungsvariablen

Funktionsweise

1. Sitzungsstart: start_session startet den Expo-Dev-Server, wartet auf die Geräteverbindung und erwirbt ein Lease

2. Gerätebindung: Die verbundene Geräte-ID wird mit einer 2-minütigen TTL in der Sitzung gespeichert

3. Automatische Injektion: Alle Maestro-Gerätetools verwenden automatisch die Geräte-ID der Sitzung

4. Lease-Verlängerung: Jeder Aufruf eines Gerätetools setzt den Lease-Timer zurück

5. Sitzungsende: stop_session bereinigt alles, oder das Lease läuft nach Inaktivität ab

Nicht-interaktive Umgebungen (CI/CD, KI-Agenten)

Dieser MCP-Server aktiviert automatisch den --offline-Modus, wenn er in CI-Umgebungen (CI=1) ausgeführt wird. Dies ermöglicht es der App, ohne ein EXPO_TOKEN zu funktionieren.

Was der Offline-Modus bewirkt

• Überspringt die Expo-Server-Kommunikation (Manifest-Signierung)

• Beeinflusst NICHT die Netzwerkfunktionen Ihrer App (API-Aufrufe, Fetch usw.)

• Der Tunnel-Modus (--tunnel) ist im Offline-Modus nicht verfügbar

Falls Sie Expo-Account-Funktionen benötigen

Für Funktionen, die eine Expo-Authentifizierung erfordern, deaktivieren Sie den Offline-Modus und geben Sie ein EXPO_TOKEN an:

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

Rufen Sie dann start_session mit offline: false auf:

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

Anforderungen

• Node.js >= 18

• Xcode (für iOS-Simulator)

• Android Studio (für Android-Emulator)

• Maestro CLI (für UI-Automatisierung)

Lizenz

MIT