JinDaGe - expo-android MCP Details

article

README

🚀 expo-android

expo-android 是一个用于通过 ADB 实现 Android 模拟器自动化的 MCP 服务器，可帮助开发者更高效地进行 Android 设备的自动化操作。

🚀 快速开始

启动一个模拟器或连接一台设备。
运行 doctor 命令来验证 ADB 和设备选择。
使用 inspect、tapElement、inputText 等工具进行操作。

示例代码如下：

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

✨ 主要特性

支持通过 ADB 对 Android 模拟器或设备进行自动化操作。
提供多种工具，如设备列表查看、元素检查、点击、输入文本等。
支持灵活的搜索条件，方便查找元素。
可与 Claude Code CLI 和 OpenAI Codex CLI 集成使用。

📦 安装指南

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

💻 使用示例

基础用法

// 验证 ADB 和设备选择
await client.callTool({ name: 'expo-android.doctor', arguments: {} });
// 检查 UI 元素
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" }

其他使用示例

检查 UI 元素

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

验证 ADB 和设备

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 },
});

📚 详细文档

环境变量

| 属性 | 详情 | |------|------| | ADB_PATH | 默认值为 adb，指定 ADB 可执行文件的路径。 | | ADB_SERIAL | 可选，目标设备的序列号（auto 表示清除并自动检测）。 | | ADB_TIMEOUT_MS | 默认值为 15000，ADB 命令的超时时间。 | | ADB_MAX_BUFFER_MB | 默认值为 10，最大输出缓冲区大小。 | | ADB_DEBUG | 默认值为 0，是否将 ADB 诊断信息记录到标准错误输出。 | | MCP_TRANSPORT | 默认值为 stdio，传输方式：stdio、http 或 both。 | | PORT | 默认值为 7332，使用 http 或 both 时的 HTTP 端口。 |

工具列表

工具通过 MCP 服务器名称公开，例如：expo-android.tap。

devices：列出已连接的设备和模拟器。
doctor：验证 ADB 可用性并显示已连接的设备。
setDevice：覆盖此 MCP 进程的活动设备序列号。
inspect：将 UI 转储解析为元素并提供摘要（可选截图）。
screenshot：仅捕获截图（Base64 或文件路径）。
findElement：返回符合搜索条件的元素。
tapElement：查找元素并点击其中心。
waitForElement：等待元素出现（可选状态检查）。
assertElement：验证元素的存在和状态。
tap：在指定的 x/y 坐标处点击。
swipe：在坐标之间滑动。
longPress：在坐标处长按。
inputText：在焦点字段中输入文本。
keyEvent：发送 Android 按键事件（例如，返回、主页）。
openApp：通过包名启动应用程序。
listPackages：列出已安装的包名。

搜索条件

findElement、tapElement、waitForElement、assertElement 这些工具接受灵活的搜索输入。常见字段：

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

🔧 技术细节

要求

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

验证 ADB：

adb devices

故障排除

ADB 未找到（spawn adb ENOENT）

如果出现 ADB executable not found 或 spawn adb ENOENT 之类的错误，请设置 ADB_PATH 或导出 SDK 路径：

export ADB_PATH="$HOME/Library/Android/sdk/platform-tools/adb"
# 或者
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

expo-android