# 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](https://github.com/senzhk/ADBKeyBoard) 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
     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](https://github.com/senzhk/ADBKeyBoard) and install: `adb install ADBKeyboard.apk`.

## Configuration

### macOS / Linux

```json
{
  "mcpServers": {
    "open-mobile-mcp": {
      "command": "npx",
      "args": ["open-mobile-mcp"]
    }
  }
}
```

### Windows

```json
{
  "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.

<details>
<summary>Running from source</summary>

```bash
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.
</details>

## 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:

```typescript
// 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