claude-in-mobile

Claude in Mobile

Use this skill for claude-in-mobile MCP and native CLI workflows.

What It Is

claude-in-mobile is an MCP server plus a native CLI for automating Android, iOS Simulator, macOS desktop apps, Aurora OS devices, Chrome/Chromium sessions, quality checks, and app-store release operations. It exposes token-efficient meta-tools instead of many single-purpose tools.

MCP Configuration

For Codex:

codex mcp add mobile -- npx -y claude-in-mobile

For Claude Code:

claude mcp add --scope user --transport stdio mobile -- npx claude-in-mobile@latest

Equivalent JSON config:

{
  "mcpServers": {
    "mobile": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "claude-in-mobile@latest"]
    }
  }
}

Use MCP tools for interactive agent automation. Use the native CLI for scripts, CI smoke tests, local setup, or quick manual checks. Check the current package with npm view claude-in-mobile version before pinning a version.

Requirements

• Android: adb in PATH, plus a connected USB-debuggable device or emulator.
• iOS: macOS, Xcode, a booted iOS Simulator, and WebDriverAgent/Appium xcuitest for full UI tree inspection.
• Desktop: macOS and Accessibility permission for the automation host.
• Aurora OS: audb/audb-client, SSH enabled on the device, and Python installed on the device for tap and swipe support.
• Browser: Chrome or Chromium reachable through CDP when using browser tools.
• Store publishing: platform credentials and explicit package/artifact/track confirmation before upload, rollout, promote, halt, or submit operations.

Run claude-in-mobile doctor first when setup is uncertain. It checks common dependencies such as ADB, Android SDK paths, Xcode/simctl, Appium/WDA, JDK, audb-client, and Chrome.

Android Via Labby

When using the Labby gateway, do not conclude that claude-in-mobile is broken just because the first device list shows no Android target. The gateway may have a working claude-in-mobile server while no device is attached yet, or while host ADB is bound only to loopback.

Use this recovery sequence before giving up:

# 1. Confirm the upstream is connected.
labby gateway list | rg -i 'claude-in-mobile|mobile'

# 2. Ask claude-in-mobile what it can see through Labby.
labby gateway code exec --json --code \
  'async () => await codemode.claude_in_mobile.device({ action: "list" })'

# 3. If Android is missing or system info reports ADB connection refused to
#    172.19.0.1:5037, restart host ADB so gateway/container clients can reach it.
adb kill-server
adb -a start-server
ss -ltnp | rg ':5037'

# 4. If no Android device is attached, boot an emulator instead of stopping.
avdmanager list avd
/path/to/Android/Sdk/emulator/emulator -avd <name> \
  -no-window -no-audio -no-boot-anim -no-snapshot \
  -gpu off -camera-back none -camera-front none

# 5. Wait for the emulator, then re-check both ADB and Labby.
adb devices -l
adb -s emulator-5554 shell getprop sys.boot_completed
labby gateway code exec --json --code \
  'async () => await codemode.claude_in_mobile.device({ action: "list" })'

Important details:

• Labby-hosted claude-in-mobile may reach the host ADB daemon through a Docker bridge address such as 172.19.0.1:5037; host ADB listening on 127.0.0.1:5037 is not enough. adb -a start-server binds it for gateway access.
• If an AVD appears to exit immediately, rerun the emulator in the foreground with -verbose and headless-safe flags instead of assuming the emulator is unavailable. A successful headless launch should eventually show control console listening on port 5554, ADB on port 5555.
• After Labby sees emulator-5554, use the MCP app/system tools to install, launch, capture screenshots, and collect crash logs.

Core Tool Families

• device: list devices, set/get active target, and enable/disable modules.
• input: tap, long press, swipe, text, and key events.
• screen: capture and annotate screenshots.
• ui: inspect trees, find elements, tap text, wait, and assert UI state.
• app: launch, stop, install, and list apps.
• system: shell, logs, info, URLs, clipboard, permissions, files, and metrics.
• flow_batch: execute multiple sequential operations in one round trip.
• flow_run: run conditional or repeated automation flows.
• flow_parallel: fan out the same action across multiple devices.

Quality tools:

• accessibility: audit for labels, touch targets, focus order, and duplicates.
• visual: save baselines and compare screenshots for visual regressions.
• recorder: record and replay taps, swipes, and text input.
• sync: coordinate multi-device test barriers.
• autopilot: explore apps with BFS/DFS and self-healing locators.
• performance: collect CPU, memory, FPS, and snapshot metrics.

Optional modules:

• browser: Chrome/Chromium navigation, clicks, form fill, screenshots, and JS.
• desktop: app launch, windows, focus, resize, clipboard, performance, and monitor operations.
• store: Google Play, Huawei AppGallery, and RuStore upload/release workflows.

Common Workflows

Device discovery: list connected devices, set the active target, then capture a screenshot before taking action.

Visual inspection: capture an annotated screenshot, inspect the UI tree, then tap by text, accessibility label, resource id, or screenshot index. Prefer semantic locators over raw coordinates.

Cross-platform app smoke test: launch the app on Android and iOS, wait for the first screen, assert expected text, capture screenshots, and collect logs on failure.

QA pass: run accessibility audit, capture a visual baseline or compare against one, record a short repro if useful, and take performance snapshots around the interaction under test.

Desktop app test: enable the desktop module, launch or attach to the macOS app, focus the window, resize to a stable viewport, inspect windows, then drive clicks and keyboard input.

Browser test: enable or call the browser module, open/navigate to the URL, snapshot DOM refs, click/fill by ref or selector, wait for selectors, and capture visual evidence.

Store release: confirm package name, artifact path, store, track, and rollout intent before uploading or submitting. Treat store actions as destructive.

See references/tooling.md for setup commands, platform details, and coordinate handling.

Native CLI Examples

These examples assume the native CLI binary is installed via Homebrew or a release artifact. The npm package is primarily used for MCP stdio startup.

claude-in-mobile doctor
claude-in-mobile screenshot android
claude-in-mobile tap android 540 960 --from-size 540x960
claude-in-mobile input android "hello world"
claude-in-mobile ui-dump android | grep "Login"
claude-in-mobile store upload --package com.example.app --file app.aab

Guardrails

• Verify the active target before any destructive action.
• Prefer UI text or accessibility identifiers over raw coordinates when possible.
• Raw tap/swipe coordinates are interpreted in the most recent screenshot's pixel space and may be auto-scaled. UI-tree coordinates are device coordinates. Do not mix them blindly.
• Collect screenshots and logs before changing app/device state during bug investigation.
• Treat system shell, file operations, permission changes, and store actions as privileged operations.
• Do not run store publishing, rollout, or destructive device commands without explicit package, artifact, and target confirmation.