phantom-mcp

一个 MCP 服务器，允许 Claude Code 查看和控制 iOS 模拟器、Android 模拟器和真实设备。提供 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`	通过 bundle ID / 包名启动应用
`kill_app`	关闭应用

分析与自动化 (Tier 3)

工具	描述
`accessibility_audit`	可访问性审计：缺失标签、点击目标过小、图片缺少 alt 文本
`test_report`	自动测试报告：start 开始跟踪，end 生成 markdown。每个操作都会自动记录。
`visual_diff`	逐像素比较两张截图以检测视觉回归
`multi_device`	在一条命令中对多个设备执行相同操作

自动运行机制

设备选择

Phantom 不会自动启动设备。它会要求你选择：

如果只有一个设备处于活动状态，它会自动使用该设备
如果有多个设备，它会要求你使用 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 执行（无 shell）
输入通过正则表达式验证：bundle ID、UDID、包名、AVD 名称、URL
iOS 谓词已转义（防止注入）
Android 文本已为设备 shell 转义
零 as any，零 exec() shell

配置

可选环境变量：

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 / 深层链接