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 :
- Si 1 seul device est actif, il l'utilise automatiquement
- Si plusieurs, il te demande de choisir avec
set_device - 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, zeroexec()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