expo-android

MCP server for Android emulator automation via ADB.

Requirements

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

Verify adb:

adb devices

Install

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

Quickstart

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

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" }

Serial selection priority: serial param (per tool call) → setDevice override → ADB_SERIAL env → auto (if only one device).

Environment variables

Variable	Default	Description
ADB_PATH	adb	Path to adb executable
ADB_SERIAL	optional	Device serial to target (auto to clear and auto-detect)
ADB_TIMEOUT_MS	15000	Timeout for adb commands
ADB_MAX_BUFFER_MB	10	Max output buffer size
ADB_DEBUG	0	Log adb diagnostics to stderr
MCP_TRANSPORT	stdio	Transport: stdio, http, or both
PORT	7332	HTTP port when using http/both

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.

Tests

npm run build
npm test

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.

Search criteria

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

Common fields:

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

MCP usage examples

Inspect

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

Inspect options:

• includeScreenshot (default: false)
• screenshotMode: base64 or path
• screenshotPath: optional file path when using path
• maxElements: limit elements returned
• includeElements: return elements or summary only

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