open-mobile-mcp
Automates Android devices: capture screenshots, UI hierarchy, OCR, perform taps, swipes, typing, read logs, manage app lifecycle, and more.
Manages Expo dependencies by running npx expo install and provides bundler management for React Native/Expo projects.
Automates iOS devices via Maestro: perception (screenshots, UI hierarchy), interaction (tap, swipe, type), logging, and app lifecycle management.
Manages the Metro JavaScript bundler: start, stop, and restart Metro for React Native app development.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@open-mobile-mcp take a screenshot of the current screen"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Open Mobile MCP Server 📱
An open-source Model Context Protocol (MCP) server for mobile automation. Give any LLM eyes and hands on a real Android or iOS device — screenshot, tap, swipe, read logs, and verify your app without writing test code.
Works with Claude Code, Claude Desktop, Cursor, and any other MCP-compatible client.
Features
Perception: Screenshots, semantic UI hierarchy, OCR, element finder, layout health analysis.
Interaction: Tap, swipe, type, pinch, rotate, long-press, hardware key presses.
Logging: Per-app Android log filtering via PID (pass
deviceId+packageIdto eliminate system noise). Background log watching viawait_for_log.Environment: Metro bundler management, app lifecycle, deep links, screen recording, locale switching.
Text Input: Unicode/Cyrillic/CJK/Emoji support via ADB Keyboard with automatic keyboard restore.
Related MCP server: airi-android
Prerequisites
Node.js (v18+)
ADB installed and in PATH (for Android).
Maestro (required for iOS; fallback for Android input).
Mac/Linux:
curl -Ls "https://get.maestro.mobile.dev" | bashWindows:
powershell -Command "iwr -useb https://get.maestro.mobile.dev | iex"
(Optional) ADB Keyboard — only needed for non-ASCII input (Unicode, Cyrillic, Emoji).
Download from GitHub and install:
adb install ADBKeyboard.apk.
Configuration
macOS / Linux
{
"mcpServers": {
"open-mobile-mcp": {
"command": "npx",
"args": ["open-mobile-mcp"]
}
}
}Windows
{
"mcpServers": {
"open-mobile-mcp": {
"command": "npx",
"args": ["open-mobile-mcp"],
"env": {
"MAESTRO_HOME": "C:\\Users\\YOUR_USER\\.maestro",
"PATH": "C:\\Users\\YOUR_USER\\.maestro\\maestro\\bin;C:\\Windows\\system32;C:\\Windows;..."
}
}
}
}Note: On Windows, explicitly setting
MAESTRO_HOMEandPATHis often required formaestroto be found.
git clone https://github.com/xzaleksey/open-mobile-mcp.git
cd open-mobile-mcp
npm install && npm run buildThen use "command": "node", "args": ["/path/to/open-mobile-mcp/build/index.js"] in your MCP config.
Tools
Perception
Tool | Platform | Description |
| Android/iOS | List connected emulators and simulators |
| Android/iOS | Screenshot (~800px wide). Use |
| Android/iOS | Pruned UI tree as JSON |
| Android/iOS | OCR via Tesseract.js (default |
| Android/iOS | Set default OCR language (e.g. |
| Android/iOS | Find elements by |
| Android/iOS | Poll until element appears (default 20s) |
| Android/iOS | Cropped screenshot of a specific element |
| — | Compare two base64 screenshots, returns diff % |
| Android/iOS | Detect deep nesting and layout performance issues |
Interaction
Tool | Platform | Description |
| Android/iOS | Recommended — find + tap by selector. Note: text matching is exact; emoji prefixes (e.g. |
| Android/iOS | Raw coordinate tap. Must use original device pixels, not screenshot pixels. |
| Android/iOS | Swipe by coordinates |
| Android/iOS | Type text (handles Unicode) |
| Android | Two-finger pinch/zoom |
| Android | Two-finger rotation |
| Android/iOS | Hardware keys: |
Environment & Logs
Tool | Platform | Description |
| Android/iOS | Start/stop/restart Metro. Pass |
| Android/iOS | Manual control over |
| Android/iOS | Recent Metro/Android/iOS logs. Returns |
| Android/iOS | Recent error/exception lines across all sources |
| Android/iOS | Network logcat lines. For iOS, filters the internal log capture buffer (enable via |
| Android/iOS | Block until a log pattern matches. See subagent pattern below. |
| Android/iOS | Launch, stop, install, or uninstall apps |
| Android/iOS | Open a URL or deep link |
| Android/iOS | Reset app to fresh-install state |
| Android | Version, permissions, install date |
| Android/iOS | Screen recording to |
| Android/iOS | Run a Maestro YAML flow |
| — | Run |
| — | Run |
wait_for_log — Background Subagent Pattern
wait_for_log blocks until a pattern appears in the log buffer. Calling it directly in the main agent freezes the conversation. Always delegate it to a background subagent in Claude Code:
// Step 1 — spawn the watcher BEFORE the action that will trigger the log
// (In Claude Code, use Agent tool with run_in_background: true)
// Subagent prompt: "Call wait_for_log with pattern 'route: /home', timeout 60000. Report the result."
// Step 2 — perform the action in the main agent
tap_on_element({ selector: "Home", strategy: "text" });
// Step 3 — main agent continues freely; gets notified when subagent finishesLicense
MIT
Available Tools
32 toolsanalyze_layout_healthC
Analyze the UI layout for performance or health issues (e.g. deep nesting).
Inputs: deviceId (required), platform (required).
capture_diffA
Compare two base64 images and return diff percentage.
Inputs: currentBase64 (required), baselineBase64 (required).
clear_app_dataA
Clear all data and cache for an app (equivalent to Settings → App → Clear Data). Resets the app to a fresh-install state. Useful for testing onboarding or reproducing first-launch bugs.
Inputs: deviceId (required), platform (required), packageId (required).
configure_ocrA
Set the default OCR language for the session.
Inputs: language (required).
device_listA
List connected active Android emulators and iOS simulators.
Inputs: no named parameters.
device_pinchA
Perform a pinch gesture (two-finger zoom) on the device. Use 'out' to zoom in (fingers spread apart) and 'in' to zoom out (fingers come together). Works on real Android phones (no root needed) via UIAutomation MotionEvent injection.
Inputs: centerX (required), centerY (required), deviceId (required), platform (required), +3 more.
device_press_keyB
Press a hardware or system key. Also accepts raw Android keycodes as numbers.
Inputs: key (required), deviceId (required), platform (required).
device_rotate_gestureA
Perform a two-finger rotation gesture (e.g. to rotate a map or image). Positive degrees = clockwise. Android only (uses UIAutomation, no root needed).
Inputs: centerX (required), centerY (required), degrees (required), deviceId (required), +3 more.
device_swipeA
⚠️ Low-level: Swipe from (x1,y1) to (x2,y2). Use this for custom gestures or when you need precise swipe control. Use coordinates from the physical screenshot (originalWidth/originalHeight). On Android, this tool automatically scales coordinates if a display override (logical resolution) is detected.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +3 more.
device_tapA
⚠️ Low-level: Tap at raw screen coordinates. Prefer tap_on_element for reliability. Use coordinates from the physical screenshot (originalWidth/originalHeight). On Android, this tool automatically scales coordinates if a display override (logical resolution) is detected.
Inputs: x (required), y (required), deviceId (required), platform (required), +2 more.
device_typeC
Type text into the device.
Inputs: text (required), deviceId (required), platform (required), verify.
find_elementA
Find UI elements by selector. Returns elements with pre-parsed coordinates (centerX, centerY, left, top, right, bottom, width, height) ready for use. For tapping, prefer tap_on_element which does find+tap in one step.
Inputs: deviceId (required), platform (required), selector (required), strategy (required).
get_app_infoA
Get version, install date, SDK target, data directory, and granted/denied permissions for an installed app. Android only.
Inputs: deviceId (required), platform (required), packageId (required).
get_bundler_logsA
Get recent logs from Metro bundler, Android, or iOS. To wait for a specific line, use wait_for_log in a background subagent instead of polling.
Inputs: source, deviceId, tailLength.
get_element_imageC
Get a cropped screenshot of a specific UI element.
Inputs: deviceId (required), platform (required), selector (required), strategy (required).
get_network_logsA
Pull network-related logs from the device. For Android, filters logcat. For iOS, filters the internal log capture buffer (must be running via manage_platform_logs or manage_bundler). For Expo / React Native apps, all console.log output (including fetchApi network traces) is emitted under the 'ReactNativeJS' logcat tag — use filter 'ReactNativeJS' or leave default. For native Android HTTP clients use 'OkHttp'. Note: a recurring warning 'ReconnectingWebSocket: Couldn't connect to ws://:8081/inspector/network' is harmless — it means Metro bundler's DevTools WebSocket is not reachable from the device (Metro not running or port 8081 blocked). The app still works; start Metro via 'npx expo start' or 'npx react-native start' on the same network to silence it.
Inputs: deviceId (required), filter, platform, tailLength.
get_screen_textB
Get all text visible on screen using OCR.
Inputs: deviceId (required), platform (required), language.
get_semantic_hierarchyC
Get pruned, semantic UI hierarchy as JSON.
Inputs: deviceId (required), platform (required).
get_viewportA
Capture screenshot of a device. Returns the image (resized to ~800px width for efficiency) and metadata with both resized and original dimensions. Use originalWidth/originalHeight for coordinate calculations when tapping. For Android, if logicalWidth/Height are provided, they represent the UI coordinate system which may differ from the physical screenshot pixels.
Inputs: deviceId (required), platform (required).
install_depsC
Install dependencies using npx expo install.
Inputs: packages (required), projectPath.
manage_app_lifecycleC
Launch, stop, install, or uninstall apps.
Inputs: action (required), target (required), deviceId (required), platform (required), +1 more.
manage_bundlerB
Start, stop, or restart the Metro bundler. Platform logs (Android/iOS) auto-start by default. On Android, pass both deviceId and packageId to enable PID-based log filtering — this captures only your app's logs and eliminates all system/GMS noise.
Inputs: action (required), command, deviceId, logFilter, +4 more.
manage_platform_logsA
Manually start/stop platform log capture (optional - auto-starts with bundler). On Android, pass both deviceId and packageId to enable PID-based filtering — this captures only your app's logs and eliminates all system/GMS noise. Without packageId, falls back to ReactNative/AndroidRuntime tag filtering which may include unrelated system warnings.
Inputs: action (required), platform (required), deviceId, logFilter, +3 more.
open_deep_linkC
Open a deep link or URL on the device.
Inputs: url (required), deviceId (required), platform (required), verify.
run_doctorC
Run npx expo-doctor.
Inputs: projectPath.
run_maestro_flowC
Run a complex Maestro flow via YAML.
Inputs: deviceId (required), flowYaml (required).
start_recordingC
Start screen recording on the device. Use an absolute path for localPath when stopping to ensure you can find the file.
Inputs: deviceId (required), platform (required).
stop_recordingA
Stop screen recording and save the file. Use an absolute path for localPath to ensure you can find the file.
Inputs: deviceId (required), platform (required), localPath (required).
stream_errorsA
Get recent error logs from Metro, Android, and iOS. To wait for a specific error, use wait_for_log(pattern: 'error|exception') in a background subagent instead of polling.
Inputs: deviceId, tailLength.
tap_on_elementA
🥇 RECOMMENDED: Tap on a UI element by selector. Finds the element and taps its center automatically. Prefer over device_tap. If observing a log triggered by this tap, spawn the wait_for_log subagent BEFORE tapping. NOTE: text matching is exact — if an element renders with an emoji prefix (e.g. '🇫🇷 French A2'), passing 'French A2' will fail. Use get_semantic_hierarchy first to see the exact text, or use contentDescription/testId strategy instead.
Inputs: deviceId (required), platform (required), selector (required), strategy (required), +2 more.
wait_for_elementC
Wait for a UI element to appear (polls every 1s).
Inputs: deviceId (required), platform (required), selector (required), strategy (required), +1 more.
wait_for_logA
Block until a log line matching a pattern appears, or timeout. Returns {matched, line, elapsed}.
ALWAYS use via background subagent — never call directly or it blocks the whole conversation:
Spawn background subagent: 'Call wait_for_log(pattern, timeout). Report result.'
Then perform the action (tap/navigate) in the main agent
Main agent continues; subagent notifies when pattern matched
Spawn subagent BEFORE the action that triggers the log, not after.
Inputs: pattern (required), source, timeout, deviceId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
UI interaction tools like tap_on_element, device_tap, and find_element are differentiated by descriptions, but the logging cluster (manage_bundler, manage_platform_logs, get_bundler_logs, get_network_logs, stream_errors, wait_for_log) has substantial overlap in purpose and requires careful reading. get_semantic_hierarchy and get_screen_text also both retrieve visible content, though through different mechanisms.
Multiple conventions coexist: get_* for inspection, device_* for low-level actions, manage_* for lifecycle operations, and standalone verb phrases like tap_on_element and wait_for_log. The clusters are internally consistent, but the overall set mixes noun-first device_* names with verb-first action names, and device_list is a noun phrase rather than a verb_noun pattern.
32 tools is a heavy surface for a mobile testing server and exceeds the point where the toolset becomes hard to navigate. Several logging and UI inspection tools could reasonably be consolidated or split into sub-servers, even though most individual tools have a defined purpose.
The toolset covers core mobile testing workflows: device management, UI inspection and interaction, gestures, app lifecycle, logging, recording, deep links, and project tooling. Missing orientation control and a few native device actions are minor gaps that can be worked around with existing low-level gestures and commands.
Maintenance
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
MCP-Native LLM Orchestration Agent
Mozark's MCP server for AI-powered app testing: device access, test automation, and QA insights.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables scalable mobile automation for iOS and Android through a platform-agnostic interface, allowing LLMs to interact with mobile applications via accessibility snapshots or screenshot-based inputs.1945,799 npm2Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA MCP server that enables LLMs to control Android devices via ADB, supporting input, UI hierarchy, device management, and shell commands.16MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that enables LLMs to control Android devices via ADB, providing tools for screen interaction and UI inspection.1MIT
- AlicenseAqualityCmaintenanceA Model Context Protocol server for ad-hoc UI testing of Android and iOS apps, enabling LLM agents to interact with mobile app UIs and react to observations.407 npm3MIT