phantom-mcp

MCP server that allows Claude Code to see and control iOS simulators, Android emulators, and real devices. 24 tools to test mobile apps without leaving the terminal.

Claude can take screenshots, read the screen, tap, scroll, fill in fields, verify assertions, record videos — automatically, on iOS and Android.

A test report with screenshots is generated automatically at the end of each test session.

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

Related MCP server: mobile-device-mcp

Prerequisites

Installation

Option A — npm (recommended)

# 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 — from source

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"

The 24 tools

Device management

Observation

Assertions

Interaction

Navigation

Device actions

App lifecycle

Analysis & Automation (Tier 3)

Automatic operation

Device selection

Phantom never boots a device automatically. It asks you to choose:

1. If only 1 device is active, it uses it automatically

2. If multiple, it asks you to choose with set_device

3. If none, it shows you the list of available devices

Auto-launch WDA (iOS)

WebDriverAgent is launched automatically on the first iOS tool that needs it. First launch ~60-90s (Xcode build), then instantaneous.

ADB multi-device (Android)

All ADB commands target the device selected via -s <serial>. No multi-device confusion.

Text entry (AZERTY compatible)

Entry uses pbcopy + Cmd+V (paste) instead of the virtual keyboard. It is instantaneous and works on all keyboard layouts (AZERTY, QWERTY, etc.).

Automatic test report

Each action (tap, type, swipe, assert...) is automatically recorded with a screenshot. At the end of the test, a markdown report is generated in /tmp/phantom-report-xxx/.

Security

• All system commands go through execFile (no shell)

• Inputs validated by regex: bundle IDs, UDIDs, package names, AVD names, URLs

• iOS predicates escaped (anti-injection)

• Android text escaped for the device shell

• Zero as any, zero exec() shell

Configuration

Optional environment variables:

• PHANTOM_WDA_PATH — path to WebDriverAgent (default: ~/.appium/...)

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

Contributing

See CONTRIBUTING.md for local setup, the pattern for adding a new tool, naming conventions, and the PR workflow.

See also:

• docs/LIMITATIONS.md — known limitations + workarounds

• docs/PATTERNS.md — practical recipes (iOS DatePicker, bottom sheets, etc.)

• docs/FEATURE_REQUESTS.md — prioritized features for upcoming versions

• docs/CHANGES_2026-04-30.md — release notes v2.3.0

Troubleshooting

WDA crash in a loop

MobAI or another tool is using port 8100.

lsof -i :8100
pkill -f "MobAI"

"No device available"

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

WDA does not start

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 not found

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

Project structure

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