Expo Android MCP

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