phantom-mcp

Claude CodeがiOSシミュレーター、Androidエミュレーター、および実機を視覚的に確認・制御できるようにするMCPサーバーです。ターミナルを離れることなくモバイルアプリをテストするための22種類のツールを提供します。

Claudeは、iOSおよびAndroid上で、スクリーンショットの撮影、画面の読み取り、タップ、スクロール、フィールド入力、アサーションの検証、動画録画を自動的に実行できます。

テストセッションごとに、スクリーンショット付きのテストレポートが自動的に生成されます。

アーキテクチャ

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

前提条件

ツール	用途	確認方法
macOS 13+	すべて	-
Xcode 15+	iOS	`xcode-select -p`
Node.js 18+	すべて	`node --version`
Appium 3+	iOS (WDA)	`appium --version`
xcuitest driver	iOS (WDA)	`appium driver list --installed`
Android SDK	Android	`adb version`

インストール

オプションA — npm (推奨)

# 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

オプションB — ソースからビルド

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"

22種類のツール

デバイス管理

ツール	説明
`list_devices`	すべてのデバイス（iOSシミュレーター、Androidエミュレーター、実機）を一覧表示
`set_device`	アクティブなデバイスを選択。オフの場合は自動的に起動

観測

ツール	説明
`screenshot`	アクティブなデバイスのスクリーンショットを撮影
`get_ui_tree`	各要素のインデックス [N] を含むアクセシビリティツリーを取得
`wait_for_element`	要素が表示されるまで待機（タイムアウト付き）
`scroll_until_visible`	要素が見つかるまでスクロール

アサーション

ツール	説明
`assert_visible`	テキストが画面上に存在することを確認
`assert_not_visible`	テキストが画面上に存在しないことを確認

インタラクション

ツール	説明
`tap`	タップ（インデックス、座標、またはテキスト指定）
`long_press`	長押し（コンテキストメニュー用）
`type_text`	テキスト入力（クリアオプション付き）
`swipe`	スワイプ（上下左右）

デバイス操作

ツール	説明
`shake`	シェイクをシミュレート
`rotate`	画面の向きを変更（縦/横）
`video_record`	動画録画の開始/停止

アプリのライフサイクル

ツール	説明
`launch_app`	バンドルID / パッケージ名でアプリを起動
`kill_app`	アプリを終了

分析 & 自動化 (Tier 3)

ツール	説明
`accessibility_audit`	アクセシビリティ監査：ラベルの欠落、タップターゲットの小ささ、altテキストのない画像などを検出
`test_report`	自動テストレポート：startで追跡開始、endでMarkdownを生成。各アクションは自動的に記録されます。
`visual_diff`	2つのスクリーンショットをピクセル単位で比較し、視覚的な回帰を検出
`multi_device`	1つのコマンドで複数のデバイスに対して同じアクションを実行

自動化の仕組み

デバイスの選択

Phantomはデバイスを自動的に起動することはありません。以下の手順で選択を求めます：

アクティブなデバイスが1つだけの場合、自動的にそれを使用します。
複数のデバイスがある場合、set_deviceで選択を求めます。
デバイスがない場合、利用可能なデバイスのリストを表示します。

WDAの自動起動 (iOS)

WebDriverAgentは、iOSツールが初めて呼び出されたときに自動的に起動します。初回起動時は約60〜90秒（Xcodeビルドのため）かかりますが、以降は即座に実行されます。

ADBマルチデバイス (Android)

すべてのADBコマンドは -s <serial> を介して選択されたデバイスをターゲットにします。マルチデバイス環境でも混乱は生じません。

テキスト入力 (AZERTY対応)

仮想キーボードの代わりに pbcopy + Cmd+V (ペースト) を使用します。これにより、キーボードレイアウト（AZERTY、QWERTYなど）に関係なく即座に入力可能です。

自動テストレポート

各アクション（タップ、入力、スワイプ、アサーションなど）は、スクリーンショットと共に自動的に記録されます。テスト終了時に、/tmp/phantom-report-xxx/ にMarkdownレポートが生成されます。

セキュリティ

すべてのシステムコマンドは execFile を経由（シェルは使用しません）
バンドルID、UDID、パッケージ名、AVD名、URLなどの入力は正規表現で検証
iOS述語はエスケープ処理済み（インジェクション対策）
Androidテキストはデバイスシェル用にエスケープ処理済み
as any や exec() シェルは一切不使用

設定

オプションの環境変数：

PHANTOM_WDA_PATH — WebDriverAgentへのパス（デフォルト: ~/.appium/...）
PHANTOM_WDA_URL — WDAのURL（デフォルト: http://localhost:8100）

トラブルシューティング

WDAがループしてクラッシュする

MobAIや他のツールがポート8100を使用しています。

lsof -i :8100
pkill -f "MobAI"

「利用可能なデバイスがありません」

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

WDAが起動しない

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が見つからない

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

プロジェクト構造

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

phantom-mcp

phantom-mcp

アーキテクチャ

前提条件

インストール

オプションA — npm (推奨)

オプションB — ソースからビルド

22種類のツール

デバイス管理

観測

アサーション

インタラクション

ナビゲーション

デバイス操作

アプリのライフサイクル

分析 & 自動化 (Tier 3)

自動化の仕組み

デバイスの選択

WDAの自動起動 (iOS)

ADBマルチデバイス (Android)

テキスト入力 (AZERTY対応)

自動テストレポート

セキュリティ

設定

トラブルシューティング

WDAがループしてクラッシュする

「利用可能なデバイスがありません」

WDAが起動しない

ADBが見つからない

プロジェクト構造

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

ツール	説明
`deep_link`	URL / ディープリンクを開く