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

| Outil | Requis pour | Comment verifier | |-------|------------|-----------------| | macOS 13+ | tout | - | | Xcode 15+ | iOS | xcode-select -p | | Node.js 18+ | tout | node --version | | Appium 3+ | iOS (WDA) | appium --version | | xcuitest driver | iOS (WDA) | appium driver list --installed | | Android SDK | Android | adb version |

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

| Tool | Description | |------|-------------| | list_devices | Liste tous les devices (iOS sims + Android emus + vrais devices) | | set_device | Selectionne le device actif. Boot auto si eteint |

Observation

| Tool | Description | |------|-------------| | screenshot | Capture l'ecran du device actif | | get_ui_tree | Arbre d'accessibilite avec index [N] pour chaque element | | wait_for_element | Attend qu'un element apparaisse (avec timeout) | | scroll_until_visible | Scroll jusqu'a trouver un element |

Assertions

| Tool | Description | |------|-------------| | assert_visible | Verifie qu'un texte EST a l'ecran | | assert_not_visible | Verifie qu'un texte N'EST PAS a l'ecran |

Interaction

| Tool | Description | |------|-------------| | tap | Tape (par index, coordonnees, ou texte) | | long_press | Appui long (menus contextuels) | | type_text | Saisie de texte avec option clear | | swipe | Swipe (up/down/left/right) |

Navigation

| Tool | Description | |------|-------------| | deep_link | Ouvre une URL / deep link |

Device actions

| Tool | Description | |------|-------------| | shake | Simule un shake | | rotate | Change l'orientation (portrait/landscape) | | video_record | Demarre/arrete l'enregistrement video |

App lifecycle

| Tool | Description | |------|-------------| | launch_app | Lance une app par bundle ID / package name | | kill_app | Ferme une app |

Analyse & Automation (Tier 3)

| Tool | Description | |------|-------------| | accessibility_audit | Audit accessibilite : labels manquants, tap targets trop petits, images sans alt text | | test_report | Rapport de test automatique : start pour commencer le suivi, end pour generer le markdown. Chaque action est tracee automatiquement. | | visual_diff | Compare deux screenshots pixel par pixel pour detecter les regressions visuelles | | multi_device | Execute la meme action sur plusieurs devices en une commande |

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