Skip to main content
Glama
open-mobile-mcp

open-mobile-mcp

by xzaleksey

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 + packageId to eliminate system noise). Background log watching via wait_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

  1. Node.js (v18+)

  2. ADB installed and in PATH (for Android).

  3. Maestro (required for iOS; fallback for Android input).

    • Mac/Linux: curl -Ls "https://get.maestro.mobile.dev" | bash

    • Windows:

      powershell -Command "iwr -useb https://get.maestro.mobile.dev | iex"
  4. (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_HOME and PATH is often required for maestro to be found.

git clone https://github.com/xzaleksey/open-mobile-mcp.git
cd open-mobile-mcp
npm install && npm run build

Then use "command": "node", "args": ["/path/to/open-mobile-mcp/build/index.js"] in your MCP config.

Tools

Perception

Tool

Platform

Description

device_list

Android/iOS

List connected emulators and simulators

get_viewport

Android/iOS

Screenshot (~800px wide). Use originalWidth/originalHeight for tap coordinates — the image is scaled down, tapping at image pixels will miss.

get_semantic_hierarchy

Android/iOS

Pruned UI tree as JSON

get_screen_text

Android/iOS

OCR via Tesseract.js (default eng)

configure_ocr

Android/iOS

Set default OCR language (e.g. eng+fra)

find_element

Android/iOS

Find elements by testId, text, or contentDescription

wait_for_element

Android/iOS

Poll until element appears (default 20s)

get_element_image

Android/iOS

Cropped screenshot of a specific element

capture_diff

—

Compare two base64 screenshots, returns diff %

analyze_layout_health

Android/iOS

Detect deep nesting and layout performance issues

Interaction

Tool

Platform

Description

tap_on_element

Android/iOS

Recommended — find + tap by selector. Note: text matching is exact; emoji prefixes (e.g. 🇫🇷 French A2) break text matching — check get_semantic_hierarchy for exact text first.

device_tap

Android/iOS

Raw coordinate tap. Must use original device pixels, not screenshot pixels.

device_swipe

Android/iOS

Swipe by coordinates

device_type

Android/iOS

Type text (handles Unicode)

device_pinch

Android

Two-finger pinch/zoom

device_rotate_gesture

Android

Two-finger rotation

device_press_key

Android/iOS

Hardware keys: back, home, recents, enter, delete, volume_up, volume_down, power, tab, search, space, menu, dpad_*. Also accepts raw Android keycodes.

Environment & Logs

Tool

Platform

Description

manage_bundler

Android/iOS

Start/stop/restart Metro. Pass deviceId + packageId for PID-based Android log filtering.

manage_platform_logs

Android/iOS

Manual control over adb logcat / xcrun capture. Pass deviceId + packageId for per-app filtering.

get_bundler_logs

Android/iOS

Recent Metro/Android/iOS logs. Returns [status] line — if buffer is empty, capture may not be running.

stream_errors

Android/iOS

Recent error/exception lines across all sources

get_network_logs

Android/iOS

Network logcat lines. For iOS, filters the internal log capture buffer (enable via manage_platform_logs).

wait_for_log

Android/iOS

Block until a log pattern matches. See subagent pattern below.

manage_app_lifecycle

Android/iOS

Launch, stop, install, or uninstall apps

open_deep_link

Android/iOS

Open a URL or deep link

clear_app_data

Android/iOS

Reset app to fresh-install state

get_app_info

Android

Version, permissions, install date

start_recording / stop_recording

Android/iOS

Screen recording to .mp4 (Android uses screenrecord, iOS uses simctl io).

run_maestro_flow

Android/iOS

Run a Maestro YAML flow

run_doctor

—

Run npx expo-doctor

install_deps

—

Run npx expo install <packages>

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 finishes

License

MIT

Available Tools

32 tools
analyze_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.

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:

  1. Spawn background subagent: 'Call wait_for_log(pattern, timeout). Report result.'

  2. Then perform the action (tap/navigate) in the main agent

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

    B3.1/5.0

    Scored across 32 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      19
      45,799 npm
      2
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      40
      7 npm
      3
      MIT