AI导哈

Expo/React Native应用自动化服务器

用于Expo/React Native应用自动化的MCP服务器，支持Maestro集成，提供会话管理、设备租赁和UI自动化工具。

  • by DaveDev42
  • TypeScript
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 DaveDev42/expo-mcp

使用说明

世博会mcp

MCP服务器，用于与Maestro集成的Expo/React Native应用程序自动化。

特性

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

安装

作为Claude代码插件（推荐）

两个命令，然后重新启动：

# 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

然后 重新启动克劳德代码 所有的工具、代理和技能都准备好了。

安装程序标志：

/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 需要）
  • A. QA代理 (qa)用于自动移动应用程序测试
  • A. 流式写入器代理 (flow-writer)用于创建Maestro YAML测试流
  • A. 使用指南 技能(/expo-guide)参考工具和最佳实践
  • A. 验证挂钩 对没有执行证据的QA PASS判决发出警告

仅作为MCP服务器

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

npx -y github:DaveDev42/expo-mcp

使用Claude代码

手动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→ 互动→ 验证→ 报告通过/失败/包含结论。

Flow Writer代理

这 flow-writer agent检查实时应用程序并创建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 bundler日志（可按级别和来源过滤）
press_key 按一个键（Enter、Backspace、Home、Lock、Tab、Volume Up/Down）
scroll 沿某个方向滚动屏幕（默认：向下）
swipe 按方向或精确的开始/结束坐标滑动

start_session选项

选项 类型 描述
target ios-simulator android-emulator
device_id string 特定设备（iOS UUID或Android序列号）。如果省略，则自动检测
host lan tunnel
port number 服务器端口（默认值：8081，繁忙时自动递增）
clear boolean 清除Metro bundler缓存
dev boolean 开发模式（默认值：true）
minify boolean 最小化JavaScript
max_workers 人数 最大地铁工人
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实例无限期持有设备：

  1. 获取: start_session 获得2分钟的设备租赁
  2. 自动续订：每次设备工具调用(take_screenshot, tap_on等）重置2分钟计时器
  3. 过期：如果2分钟内没有调用设备工具，则租约到期，设备可用
  4. 重新收购：呼叫 start_session 再次获取（服务器保持运行，无需重新启动）
  5. 检查: get_session_status 显示剩余租赁时间

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

环境变量

变量 描述 默认值
EXPO_APP_DIR Expo应用程序目录的路径（CLI位置arg优先） 当前工作目录
MAESTRO_CLI_PATH 通往Maestro CLI的路径 ~/.maestro/bin/maestro
ESSENTIAL_TOOLS 以逗号分隔的要公开的工具列表(--tools 优先） 所有工具
EXCLUDE_TOOLS 以逗号分隔的排除工具列表(--exclude-tools 优先） 无
LOG_BUFFER_SIZE 内存中要保留的最大日志行数 400
EXPO_TOKEN Expo身份验证令牌（仅在禁用脱机模式时需要） 无

运作原理

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

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

此MCP服务器自动启用 --offline 在CI环境中运行时的模式(CI=1).这允许应用程序在不需要 EXPO_TOKEN.

离线模式有什么作用

  • Skips Expo服务器通信（清单签名）
  • 不影响 应用程序的网络功能（API调用、获取等）
  • 隧道模式(--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自动化）

许可证

麻省理工学院

相关 MCP