Skip to main content
Glama

expo-android

npm version npm downloads license node version typescript CI

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

Related MCP server: android-mcp-server

Install

Claude Desktop, one-click: download expo-android.mcpb from the latest release and drag it into Settings → Extensions. You can leave both fields empty — adb is auto-detected and the only connected device is used by default.

Via npm:

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)

The server starts even when adb is missing — tools return the ADB executable not found error until adb becomes reachable (run doctor to diagnose). To fix it, 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

Tool names are plain identifiers (e.g. tap); your MCP client prefixes them with the server name you registered.

  • 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.

  • installExpoGo — download the pinned Expo Go APK and install it via adb install -r (the url override only accepts official github.com/expo/expo-go-releases URLs).

Every tool declares MCP annotations (readOnlyHint/destructiveHint), so clients can auto-approve inspection tools and gate the ones that drive the device.

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

Available Tools

17 tools
assertElementAssert elementC
Read-only

Assert element presence and state.

Inputs: text, class, serial, resourceId, +10 more.

devicesList devicesA
Read-only

List connected Android devices and emulators.

Inputs: no named parameters.

doctorDoctorB
Read-only

Check adb availability and connected devices.

Inputs: no named parameters.

findElementFind elementC
Read-only

Find UI elements by criteria.

Inputs: text, class, serial, checkable, +8 more.

inputTextInput textC

Type text into the focused input field.

Inputs: text (required), serial.

inspectInspectB
Read-only

Capture a screenshot and parse UI hierarchy into structured elements.

Inputs: serial, maxElements, screenshotMode, screenshotPath, +3 more.

installExpoGoInstall Expo GoA

Download the pinned Expo Go APK and install it on the device via adb install -r. Pass url to install a different official Expo Go release (only github.com/expo/expo-go-releases URLs are accepted).

Inputs: url, serial.

keyEventKey eventC

Send an Android key event to the device.

Inputs: keyCode (required), serial.

listPackagesList packagesB
Read-only

List installed package names.

Inputs: filter, serial.

longPressLong pressC

Press and hold on screen at coordinates.

Inputs: x (required), y (required), serial, duration.

openAppOpen appB

Launch an Android app by package name.

Inputs: packageName (required), serial.

screenshotScreenshotA
Read-only

Capture a screenshot without UI element parsing.

Inputs: mode, path, serial.

setDeviceSet deviceA
Idempotent

Override the active device serial for this MCP process. Use "auto" to clear override.

Inputs: serial.

swipeSwipeB

Swipe on screen from one coordinate to another.

Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more.

tapTapC

Tap on screen at coordinates.

Inputs: x (required), y (required), serial.

tapElementTap elementC

Find an element and tap its center coordinate.

Inputs: text, class, index, serial, +8 more.

waitForElementWait for elementB
Read-only

Wait until an element appears or timeout is reached.

Inputs: text, class, serial, timeout, +11 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools are clearly distinct, such as screenshot vs. inspect (with UI parsing) and coordinate-based tap vs. element-based tapElement. Minor overlap exists between devices and doctor, both listing devices, but descriptions differentiate their purposes.

    Naming Consistency3/5

    Naming mixes imperative verbs (tap, swipe, inspect) with verb+noun compounds (findElement, openApp) and a few noun-only names (devices, doctor). The pattern is not fully consistent but remains readable and predictable.

    Tool Count4/5

    At 17 tools, the set is slightly above the ideal 3-15 range, but each tool serves a distinct function in device management, UI interaction, and app handling. The count feels justified for a comprehensive Android automation server.

    Completeness4/5

    The toolset covers core device lifecycle, UI inspection/interaction, and Expo Go installation. Minor gaps include lack of arbitrary APK installation or text clearing, but essential workflows are well represented.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A powerful MCP server that provides comprehensive Android device automation capabilities through ADB, enabling AI agents to interact with Android devices for testing, automation, and device control tasks.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for controlling Android devices over ADB, using direct commands and semantic accessibility selectors with a Kotlin helper APK.
      444 npm
      MIT