Expo Android MCP
MCP server for Android emulator automation via ADB.
Ask AI about Expo Android MCP
Powered by Claude Β· Grounded in docs
I know everything about Expo Android MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
- Start an emulator or connect a device.
- Run
doctorto validate adb + device selection. - 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,textContainscontentDesc,contentDescContainsresourceId,resourceIdContainsclassnormalizeWhitespace,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:base64orpathscreenshotPath: optional file path when usingpathmaxElements: limit elements returnedincludeElements: 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 },
});
