Expo Android

🚀 expo-android

MCP server for Android emulator automation via ADB.

🚀 Quick Start

1. Start an emulator or connect a device.
2. Run doctor to validate adb + device selection.
3. Use inspect, tapElement, inputText, etc.

Example:

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

✨ Features

• Automate Android emulators or connected devices via ADB.
• Provide a series of tools for device inspection, interaction, and validation.

📦 Installation

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

💻 Usage Examples

Basic Usage

# Verify adb
adb devices

Advanced Usage

Use with 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

Use with 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

Or edit ~/.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" }

MCP Usage Examples

Inspect

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

Doctor

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

Override serial per call

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

Tap element

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

Wait + assert

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

📚 Documentation

Requirements

• Node 18+
• Android SDK platform-tools (adb) available
• Android emulator or device connected

Environment variables

Search criteria

These tools accept flexible search inputs: findElement, tapElement, waitForElement, assertElement.

Common fields:

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

Tools

Tools are exposed under your MCP server name. Example: expo-android.tap.

• devices — list connected devices and emulators.
• doctor — validate adb availability and show connected devices.
• setDevice — override the active device serial for this MCP process.
• inspect — UI dump parsed into elements with a summary (screenshot optional).
• screenshot — capture a screenshot only (base64 or file path).
• findElement — return elements that match search criteria.
• tapElement — find an element and tap its center.
• waitForElement — wait until an element appears (optionally with state checks).
• assertElement — verify element existence and state.
• tap — tap at x/y coordinates.
• swipe — swipe between coordinates.
• longPress — press and hold at coordinates.
• inputText — type text in the focused field.
• keyEvent — send Android key events (e.g., BACK, HOME).
• openApp — launch an app by package name.
• listPackages — list installed package names.

🔧 Troubleshooting

adb not found (spawn adb ENOENT)

If you see an error like ADB executable not found or spawn adb ENOENT, set ADB_PATH or export an SDK path:

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

If multiple devices are connected, set ADB_SERIAL to the target device. You can also run setDevice at runtime:

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

If you update PATH or SDK variables, restart the MCP process so it can pick up the new environment.

📄 License