Open Mobile

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.

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

Tools

Perception

Interaction

Environment & Logs

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