expo-mcp

用于 Expo/React Native 应用自动化（集成 Maestro）的 MCP 服务器。

功能特性

基于会话的架构：start_session 启动 Expo、绑定设备并获取租约 — 无需手动管理设备 ID
带 TTL 的设备租约：2 分钟租约，每次调用设备工具时自动续期；闲置后过期，以便其他实例使用该设备
跨实例协调：多个 MCP 实例可同时运行，不会发生设备冲突
Expo 开发服务器管理：启动/停止/重载 Expo 开发服务器
Maestro 集成：完整的 UI 自动化工具（点击、输入、截图等）

安装

作为 Claude Code 插件（推荐）

执行两条命令，然后重启：

# 1. Install the plugin. Just dismiss the "Expo App Directory" prompt
#    (or leave it empty) — the next step configures it for you.
/plugin marketplace add DaveDev42/expo-mcp
/plugin install expo-mcp --scope project

# 2. One-shot installer. Runs environment checks, auto-detects the Expo
#    app directory, and writes the userConfig directly into
#    .claude/settings.json. No /plugin UI round-trip needed.
/expo-mcp:install                     # auto-detect
/expo-mcp:install apps/mobile         # monorepo: pass the path explicitly

然后重启 Claude Code，所有工具、代理和技能即可就绪。

安装程序标志：

/expo-mcp:install apps/mobile --global        # write to ~/.claude/settings.json
/expo-mcp:install --scaffold-maestro          # also create a starter maestro/
/expo-mcp:install --skip-doctor               # skip prerequisite checks

安装程序会运行插件目录中的捆绑 Node 脚本（doctor.mjs、detect-app-dir.mjs、scaffold-maestro.mjs）。Claude Code 首次运行时会提示您批准每一个脚本 — 请批准以继续。

如果您希望预先批准脚本（无需提示），请将其添加到项目中的 .claude/settings.local.json — 将 <PATH> 替换为 Claude Code 首次运行每个脚本时显示的绝对路径：

{
  "permissions": {
    "allow": [
      "Bash(node <PATH>/doctor.mjs:*)",
      "Bash(node <PATH>/detect-app-dir.mjs:*)",
      "Bash(node <PATH>/scaffold-maestro.mjs:*)"
    ]
  }
}

安装插件会自动配置：

expo MCP 服务器（无需手动配置 .mcp.json）
用于自动化移动应用测试的 QA 代理 (qa)
用于创建 Maestro YAML 测试流程的 流程编写代理 (flow-writer)
包含工具参考和最佳实践的 使用指南 技能 (/expo-guide)
一个 验证钩子，在没有执行证据的情况下对 QA PASS 结论发出警告

仅作为 MCP 服务器

本项目仅通过 GitHub 分发（npm 上的 expo-mcp 名称属于另一个无关的包 — 请勿使用）。通过 GitHub 引用运行它：

npx -y github:DaveDev42/expo-mcp

与 Claude Code 配合使用

手动 MCP 设置

如果不使用插件，请添加到您的 .mcp.json 中：

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp"]
    }
  }
}

Monorepo 设置

使用位置参数指定应用目录：

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile"]
    }
  }
}

指定设备

使用 --device-id 固定特定的模拟器或仿真器：

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--device-id=6D192F60-1234-5678-ABCD-000000000000"]
    }
  }
}

工具过滤

使用 --exclude-tools 排除特定工具：

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile", "--exclude-tools=list_devices"]
    }
  }
}

或使用 --tools 仅暴露特定工具：

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--tools=start_session,stop_session,take_screenshot"]
    }
  }
}

CLI 参考

Usage: expo-mcp [app-dir] [options]

Arguments:
  app-dir                      Path to Expo app directory (default: cwd)

Options:
  --device-id=<id>             Specific device to use (iOS simulator UUID or Android serial)
  --exclude-tools=tool1,tool2  Exclude specific tools from the MCP server
  --tools=tool1,tool2          Only expose specific tools
  -h, --help                   Show help message
  -v, --version                Show version number

快速入门

# 1. Start session (launches Expo + binds device + acquires lease)
start_session({ target: "ios-simulator" })

# 2. Use tools directly (no device_id needed!)
take_screenshot()
tap_on({ text: "Login" })
input_text({ text: "hello@example.com" })
press_key({ key: "Enter" })
scroll({ direction: "down" })
swipe({ direction: "left" })

# 3. Run Maestro flows
run_maestro_flow({ flow_yaml: "- assertVisible: Welcome" })
check_maestro_flow_syntax({ flow_yaml: "- tap: Login" })

# 4. Reload app after code changes
reload_app()

# 5. Check logs if needed
get_logs({ level: "error" })

# 6. Stop session when done
stop_session()

插件功能

作为 Claude Code 插件安装时，您将获得以下额外功能：

QA 代理

将移动端 QA 测试委托给 qa 代理。它会在模拟器/仿真器上系统地测试您的应用，并要求严格的证据 — 不接受仅代码审查的结论。

# In Claude Code, delegate to the QA agent:
"Test the login flow on iOS simulator"  →  delegates to qa agent

该代理遵循结构化方法：启动应用 → 检查 UI → 交互 → 验证 → 报告 PASS/FAIL/INCONCLUSIVE 结论。

流程编写代理

flow-writer 代理会检查实时应用并创建 Maestro YAML 测试流程：

# Ask the flow writer to create a test flow:
"Write a Maestro flow for the onboarding sequence"  →  delegates to flow-writer agent

它会验证语法、执行流程以验证其有效性，并将 .yaml 文件写入您的项目。

使用指南

通过 /expo-guide 访问工具参考和最佳实践：

/expo-guide                    # Full guide
/expo-guide session            # Session lifecycle
/expo-guide debugging          # Debugging tips

工具

生命周期工具

工具	描述
`get_session_status`	获取会话状态（服务器状态、设备信息、剩余租约时间）
`start_session`	启动 Expo 服务器、连接设备并获取设备租约
`stop_session`	停止 Expo 服务器并释放所有资源
`reload_app`	在已连接设备上热重载应用
`get_logs`	获取 Metro 打包器日志（可按级别和来源过滤）
`press_key`	按键（Enter、Backspace、Home、Lock、Tab、音量加/减）
`scroll`	向某个方向滚动屏幕（默认：向下）
`swipe`	按方向或精确的起始/结束坐标滑动

start_session 选项

选项	类型	描述
`target`	`ios-simulator`	`android-emulator`	`web-browser`	启动的目标平台
`device_id`	string	特定设备（iOS UUID 或 Android 序列号）。若省略则自动检测
`host`	`lan`	`tunnel`	`localhost`	连接模式
`port`	number	服务器端口（默认：8081，若被占用则自动递增）
`clear`	boolean	清除 Metro 打包器缓存
`dev`	boolean	开发模式（默认：true）
`minify`	boolean	压缩 JavaScript
`max_workers`	number	最大 Metro 工作进程数
`offline`	boolean	离线模式
`scheme`	string	自定义 URI 方案
`simulator_name`	string	iOS 模拟器名称（例如 "iPhone 16 Pro"）
`clean_state`	boolean	启动前清理模拟器状态（默认：false）
`auto_login`	object	应用加载后运行 Maestro 流程 (`{ flow_file: "path/to/flow.yaml" }`)

Maestro 工具

一旦会话激活，所有 Maestro 工具都会自动工作 — device_id 会从会话中注入：

工具	描述
`take_screenshot`	截屏（自动调整大小以适应 LLM 上下文）
`tap_on`	通过文本、ID 或坐标点击 UI 元素
`input_text`	在聚焦字段中输入文本
`back`	按返回按钮
`run_maestro_flow`	内联运行 Maestro YAML 流程
`run_maestro_flow_files`	从项目目录运行 Maestro 流程文件
`check_maestro_flow_syntax`	验证 Maestro YAML 流程语法而不运行它
`inspect_view_hierarchy`	获取当前屏幕的 UI 元素树
`list_devices`	列出所有可用设备（无需活动会话即可工作）

注意：设备工具需要活动会话。请先调用 start_session。list_devices 和 check_maestro_flow_syntax 可随时调用。

设备租约系统

设备租约可防止单个 MCP 实例无限期占用设备：

获取：start_session 获取 2 分钟的设备租约
自动续期：每次调用设备工具（take_screenshot、tap_on 等）都会重置 2 分钟计时器
过期：如果 2 分钟内没有调用设备工具，租约过期，设备变为可用状态
重新获取：再次调用 start_session 即可重新获取（服务器保持运行，无需重启）
检查：get_session_status 显示剩余租约时间

多个 MCP 实例通过基于文件的注册表 (/tmp/expo-mcp/instances/) 进行协调，因此两个实例无法同时声明同一设备。

环境变量

变量	描述	默认值
`EXPO_APP_DIR`	Expo 应用目录路径（CLI 位置参数优先级更高）	当前工作目录
`MAESTRO_CLI_PATH`	Maestro CLI 路径	`~/.maestro/bin/maestro`
`ESSENTIAL_TOOLS`	要暴露的工具的逗号分隔列表（`--tools` 优先级更高）	所有工具
`EXCLUDE_TOOLS`	要排除的工具的逗号分隔列表（`--exclude-tools` 优先级更高）	无
`LOG_BUFFER_SIZE`	内存中保留的最大日志行数	400
`EXPO_TOKEN`	Expo 身份验证令牌（仅在禁用离线模式时需要）	无

工作原理

会话启动：start_session 启动 Expo 开发服务器，等待设备连接，并获取租约
设备绑定：已连接的设备 ID 存储在具有 2 分钟 TTL 的会话中
自动注入：所有 Maestro 设备工具自动使用会话的设备 ID
租约续期：每次设备工具调用都会重置租约计时器
会话结束：stop_session 清理所有内容，或者租约在闲置后过期

非交互式环境（CI/CD、AI 代理）

当在 CI 环境 (CI=1) 中运行时，此 MCP 服务器会自动启用 --offline 模式。这允许应用在无需 EXPO_TOKEN 的情况下工作。

离线模式的作用

跳过 Expo 服务器通信（清单签名）
不会影响您应用的联网功能（API 调用、fetch 等）
隧道模式 (--tunnel) 在离线模式下不可用

如果您需要 Expo 账户功能

对于需要 Expo 身份验证的功能，请禁用离线模式并提供 EXPO_TOKEN：

{
  "mcpServers": {
    "expo": {
      "env": {
        "EXPO_TOKEN": "your-token-here"
      }
    }
  }
}

然后调用 start_session 并设置 offline: false：

start_session({ target: "ios-simulator", offline: false })

要求

Node.js >= 18
Xcode（用于 iOS 模拟器）
Android Studio（用于 Android 仿真器）
Maestro CLI（用于 UI 自动化）

许可证

MIT

Expo MCP Server