Expo Android MCP

expo-android

用于通过 ADB 自动化控制 Android 模拟器的 MCP 服务。

要求

• Node 18+
• 可用的 Android SDK platform-tools（adb）
• 已连接的 Android 模拟器或设备

验证 adb：

adb devices

安装

Claude Desktop，一键安装：从最新版本下载 expo-android.mcpb，然后将其拖入设置 → 扩展。两个字段都可以留空——系统会自动检测 adb，并默认使用唯一连接的设备。

通过 npm 安装：

npm install -g @fndchagas/expo-android
# or
npx -y @fndchagas/expo-android

快速开始

1. 启动模拟器或连接设备。
2. 运行 doctor，验证 adb 和设备选择。
3. 使用 inspect、tapElement、inputText 等工具。

示例：

await client.callTool({ name: 'expo-android.doctor', arguments: {} });
await client.callTool({
  name: 'expo-android.inspect',
  arguments: { onlyInteractive: true, maxElements: 200 },
});

与 Claude Code CLI 搭配使用

claude mcp add expo-android \
  --env ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb" \
  --env ADB_SERIAL="auto" \
  -- npx -y @fndchagas/expo-android

与 OpenAI Codex CLI 搭配使用

codex mcp add expo-android \
  --env ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb" \
  --env ADB_SERIAL="auto" \
  -- npx -y @fndchagas/expo-android

或编辑 ~/.codex/config.toml：

[mcp_servers.expo-android]
command = "npx"
args = ["-y", "@fndchagas/expo-android"]
env = { ADB_PATH = "/Users/you/Library/Android/sdk/platform-tools/adb", ADB_SERIAL = "emulator-5554" }

设备序列号选择优先级： serial 参数（每次工具调用）→ setDevice 覆盖值 → ADB_SERIAL 环境变量 → 自动选择（仅连接一台设备时）。

环境变量

变量	默认值	描述
ADB_PATH	adb	adb 可执行文件的路径
ADB_SERIAL	可选	目标设备的序列号（设为 auto 可清除并自动检测）
ADB_TIMEOUT_MS	15000	adb 命令的超时时间
ADB_MAX_BUFFER_MB	10	最大输出缓冲区大小
ADB_DEBUG	0	将 adb 诊断信息记录到 stderr
MCP_TRANSPORT	stdio	传输方式：stdio、http 或 both
PORT	7332	使用 http/both 时的 HTTP 端口

故障排除

未找到 adb（spawn adb ENOENT）

即使找不到 adb，服务也会启动——在 adb 可用之前，工具会返回 ADB executable not found 错误（运行 doctor 进行诊断）。要解决此问题，请设置 ADB_PATH 或导出 SDK 路径：

export ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb"
# or
export ANDROID_HOME="$HOME/Library/Android/sdk"

如果连接了多台设备，请将 ADB_SERIAL 设为目标设备。 你也可以在运行时执行 setDevice：

await client.callTool({
  name: 'expo-android.setDevice',
  arguments: { serial: 'emulator-5554' },
});

如果更新了 PATH 或 SDK 变量，请重启 MCP 进程，以便其读取 新的环境变量。

测试

npm run build
npm test

工具

工具名称是普通标识符（例如 tap）；MCP 客户端会在名称前加上你注册的服务名称。

• devices — 列出已连接的设备和模拟器。
• doctor — 验证 adb 是否可用，并显示已连接的设备。
• setDevice — 为此 MCP 进程覆盖当前活动设备的序列号。
• inspect — 将 UI 转储解析为元素并提供摘要（可选截图）。
• screenshot — 仅截取屏幕截图（base64 或文件路径）。
• findElement — 返回符合搜索条件的元素。
• tapElement — 查找元素并点击其中心。
• waitForElement — 等待元素出现（可选进行状态检查）。
• assertElement — 验证元素是否存在及其状态。
• tap — 点击 x/y 坐标。
• swipe — 在坐标之间滑动。
• longPress — 在坐标处按住不放。
• inputText — 在当前聚焦的字段中输入文本。
• keyEvent — 发送 Android 按键事件（例如 BACK、HOME）。
• openApp — 按包名启动应用。
• listPackages — 列出已安装的包名。
• installExpoGo — 下载指定版本的 Expo Go APK，并通过 adb install -r 安装（url 覆盖项仅接受来自官方 github.com/expo/expo-go-releases 的 URL）。

每个工具都会声明 MCP 注解（readOnlyHint/destructiveHint），因此客户端可以自动批准检查类工具，并限制驱动设备的工具。

搜索条件

以下工具接受灵活的搜索输入：findElement、tapElement、 waitForElement、assertElement。

常用字段：

• text、textContains
• contentDesc、contentDescContains
• resourceId、resourceIdContains
• class
• normalizeWhitespace、caseInsensitive

MCP 用法示例

检查

const result = await client.callTool({
  name: 'expo-android.inspect',
  arguments: { onlyInteractive: true, includeScreenshot: false, maxElements: 200 },
});

检查选项：

• includeScreenshot（默认值：false）
• screenshotMode：base64 或 path
• screenshotPath：使用 path 时的可选文件路径
• maxElements：限制返回的元素数量
• includeElements：返回元素，或仅返回摘要

Doctor

await client.callTool({
  name: 'expo-android.doctor',
  arguments: {},
});

按次调用覆盖序列号

await client.callTool({
  name: 'expo-android.tapElement',
  arguments: { text: 'Search', serial: 'emulator-5554' },
});

点击元素

await client.callTool({
  name: 'expo-android.tapElement',
  arguments: { text: 'Private account' },
});

等待并断言

await client.callTool({
  name: 'expo-android.waitForElement',
  arguments: { text: 'Save', timeout: 10000, shouldBeClickable: true },
});

await client.callTool({
  name: 'expo-android.assertElement',
  arguments: { text: 'Private account', shouldBeChecked: true },
});