phantom-mcp

MCP-Server, der es Claude Code ermöglicht, iOS-Simulatoren, Android-Emulatoren und echte Geräte zu sehen und zu steuern. 24 Tools zum Testen mobiler Apps, ohne das Terminal zu verlassen.

Claude kann Screenshots machen, den Bildschirm lesen, tippen, scrollen, Felder ausfüllen, Assertionen prüfen, Videos aufnehmen – automatisch, auf iOS und Android.

Ein Testbericht mit Screenshots wird bei jeder Testsitzung automatisch generiert.

Architektur

Claude Code
    | MCP protocol (stdio)
    v
Phantom (Node.js TypeScript)
    |                       |
    v                       v
iOS                      Android
  xcrun simctl             ADB
  WebDriverAgent           UIAutomator
  (localhost:8100)         (adb shell)
    |                       |
    v                       v
Simulateur / iPhone    Emulateur / Device

Related MCP server: mobile-device-mcp

Voraussetzungen

Installation

Option A — npm (empfohlen)

# 1. Installer le package
npm install -g phantom-mcp

# 2. Installer Appium + driver iOS
npm install -g appium
appium driver install xcuitest

# 3. Enregistrer dans Claude Code
claude mcp add -s user phantom -- npx phantom-mcp

Option B — aus den Quellen

git clone https://github.com/nthimpulse/phantom-mcp.git
cd phantom-mcp
npm install
npm run build
claude mcp add -s user phantom -- node "$(pwd)/build/index.js"

Die 24 Tools

Geräteverwaltung

Beobachtung

Assertionen

Interaktion

Navigation

Geräteaktionen

App-Lebenszyklus

Analyse & Automatisierung (Stufe 3)

Automatischer Betrieb

Geräteauswahl

Phantom bootet niemals automatisch ein Gerät. Es fordert dich auf zu wählen:

1. Wenn nur 1 Gerät aktiv ist, wird es automatisch verwendet

2. Wenn mehrere aktiv sind, wirst du aufgefordert, mit set_device zu wählen

3. Wenn keines aktiv ist, wird die Liste der verfügbaren Geräte angezeigt

Automatischer WDA-Start (iOS)

WebDriverAgent wird automatisch beim ersten iOS-Tool gestartet, das es benötigt. Erster Start ca. 60-90s (Xcode-Build), danach sofort.

ADB Multi-Device (Android)

Alle ADB-Befehle zielen auf das über -s <serial> ausgewählte Gerät ab. Keine Verwirrung bei mehreren Geräten.

Texteingabe (AZERTY-kompatibel)

Die Eingabe verwendet pbcopy + Cmd+V (Einfügen) anstelle der virtuellen Tastatur. Dies ist sofort einsatzbereit und funktioniert mit allen Tastaturlayouts (AZERTY, QWERTY usw.).

Automatischer Testbericht

Jede Aktion (Tippen, Tippen, Wischen, Assertion...) wird automatisch mit einem Screenshot aufgezeichnet. Am Ende des Tests wird ein Markdown-Bericht in /tmp/phantom-report-xxx/ generiert.

Sicherheit

• Alle Systembefehle laufen über execFile (keine Shell)

• Eingaben werden per Regex validiert: Bundle-IDs, UDIDs, Paketnamen, AVD-Namen, URLs

• iOS-Prädikate maskiert (Anti-Injection)

• Android-Text für die Geräte-Shell maskiert

• Kein as any, kein exec() Shell

Konfiguration

Optionale Umgebungsvariablen:

• PHANTOM_WDA_PATH — Pfad zu WebDriverAgent (Standard: ~/.appium/...)

• PHANTOM_WDA_URL — WDA-URL (Standard: http://localhost:8100)

Mitwirken

Siehe CONTRIBUTING.md für das lokale Setup, das Muster zum Hinzufügen eines neuen Tools, Namenskonventionen und den PR-Workflow.

Siehe auch:

• docs/LIMITATIONS.md — bekannte Einschränkungen + Workarounds

• docs/PATTERNS.md — praktische Rezepte (iOS DatePicker, Bottom Sheets, etc.)

• docs/FEATURE_REQUESTS.md — priorisierte Funktionen für die nächsten Versionen

• docs/CHANGES_2026-04-30.md — Release Notes v2.3.0

Fehlerbehebung

WDA-Endlosschleife beim Absturz

MobAI oder ein anderes Tool verwendet Port 8100.

lsof -i :8100
pkill -f "MobAI"

"Kein Gerät verfügbar"

xcrun simctl list devices available   # iOS
adb devices -l                        # Android

WDA startet nicht

cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
xcodebuild -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination "platform=iOS Simulator,name=iPhone 17 Pro" \
  test

ADB nicht gefunden

ls ~/Library/Android/sdk/platform-tools/adb

Projektstruktur

phantom/
  src/
    index.ts                Point d'entree MCP (24 tools)
    platforms/
      types.ts              Interfaces communes
      ios/
        simctl.ts            Wrapper xcrun simctl
        wda.ts               Client WDA + auto-launch
      android/
        adb.ts               Wrapper ADB complet
    tools/                   24 tools (21 fichiers)
    utils/
      device-manager.ts      Detection + routing multi-device
      xml.ts                 Parser XML partage
  docs/
    README.md               Ce fichier
    TUTORIAL.md             Tuto pas-a-pas
    FLOWS.md                Exemples de flows de test