phantom-mcp

Serveur MCP qui permet a Claude Code de voir et controler des simulateurs iOS, emulateurs Android, et vrais devices. 22 tools pour tester des apps mobiles sans quitter le terminal.

Claude peut prendre des screenshots, lire l'ecran, taper, scroller, remplir des champs, verifier des assertions, enregistrer des videos — automatiquement, sur iOS et Android.

Un rapport de test avec screenshots est genere automatiquement a chaque session de test.

Architecture

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

Prerequis

Installation

Option A — npm (recommande)

# 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 — depuis les sources

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"

Les 22 tools

Device management

Observation

Assertions

Interaction

Navigation

Device actions

App lifecycle

Analyse & Automation (Tier 3)

Fonctionnement automatique

Selection de device

Phantom ne boot jamais un device automatiquement. Il te demande de choisir :

1. Si 1 seul device est actif, il l'utilise automatiquement

2. Si plusieurs, il te demande de choisir avec set_device

3. Si aucun, il te montre la liste des devices disponibles

Auto-launch WDA (iOS)

WebDriverAgent est lance automatiquement au premier tool iOS qui en a besoin. Premier lancement ~60-90s (build Xcode), ensuite instantane.

ADB multi-device (Android)

Toutes les commandes ADB ciblent le device selectionne via -s <serial>. Pas de confusion multi-device.

Saisie de texte (AZERTY compatible)

La saisie utilise pbcopy + Cmd+V (paste) au lieu du clavier virtuel. C'est instantane et fonctionne sur tous les layouts clavier (AZERTY, QWERTY, etc.).

Rapport de test automatique

Chaque action (tap, type, swipe, assert...) est automatiquement enregistree avec un screenshot. A la fin du test, un rapport markdown est genere dans /tmp/phantom-report-xxx/.

Securite

• Toutes les commandes systeme passent par execFile (pas de shell)

• Inputs valides par regex : bundle IDs, UDIDs, package names, AVD names, URLs

• Predicats iOS echappes (anti-injection)

• Texte Android echappe pour le shell device

• Zero as any, zero exec() shell

Configuration

Variables d'environnement optionnelles :

• PHANTOM_WDA_PATH — chemin vers WebDriverAgent (defaut: ~/.appium/...)

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

Troubleshooting

WDA crash en boucle

MobAI ou un autre outil utilise le port 8100.

lsof -i :8100
pkill -f "MobAI"

"Aucun device disponible"

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

WDA ne demarre pas

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 non trouve

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

Structure du projet

phantom/
  src/
    index.ts                Point d'entree MCP (22 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/                   22 tools (19 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