lazy-mobile-mcp

Local Model Context Protocol (MCP) server for Android and iOS mobile automation with performance telemetry.

Control real devices and simulators using screenshot, tap, swipe, input_text, launch_app, dump_ui, press_key, open_url, and collect honest performance samples (cpu, memory) with session history in SQLite. Works with Codex, Claude Code, and other MCP clients over stdio.

Keywords: MCP server, mobile automation, Android ADB, iOS simulator, WebDriverAgent, devicectl, simctl, app performance telemetry.

Why This Project

• Build a local MCP bridge for AI clients over stdio.

• Automate Android via ADB and iOS via simctl / devicectl / WDA.

• Keep operations traceable with trace_id in responses and logs.

• Persist sessions, samples, artifacts, and audit events in SQLite for reproducibility.

Related MCP server: mobile-debug-mcp

Features

• stdio MCP transport for local AI tooling.

• Single active device model (select_device) with optional per-call device_id.

• Android adapter via ADB CLI (async process execution).

• iOS adapter via Xcode tools with macOS guard and graceful degradation.

• WDA endpoint auto-discovery (TTL-cached) for iOS interactive actions.

• UI dump, key press, URL/deep-link, and foreground app helpers for agent workflows.

• Risk-tiered approval policy for interactive actions.

• JSON logging and unified error contract.

• SQLite persistence for sessions, perf_samples, artifacts, audit_logs (long-lived connection + indexes).

Tool Index

• mobile.list_devices

• mobile.select_device

• mobile.get_capabilities

• mobile.screenshot

• mobile.tap

• mobile.swipe

• mobile.input_text

• mobile.launch_app

• mobile.stop_app

• mobile.dump_ui

• mobile.press_key

• mobile.open_url

• mobile.get_foreground_app

• mobile.start_perf_session

• mobile.stop_perf_session

• mobile.get_perf_samples

• mobile.list_sessions

Architecture

• TypeScript MCP server + in-process async worker (tool contracts, validation, policy, trace ID)

• Android adapter (adb)

• iOS adapter (simctl, devicectl, WDA via fetch)

• SQLite storage (artifacts/mobile.db by default; screenshots under ARTIFACTS_DIR)

Prerequisites

• Node.js 20+

• Android: adb in PATH

• iOS (optional): macOS + xcrun (simctl/devicectl)

• For iOS interactive actions (tap/swipe/input): reachable WebDriverAgent endpoint

Install

npm install

Install From npm

npm install lazy_mobile_mcp

Quick Start (Codex)

Requires codex CLI in PATH.

Published package:

npx -y lazy_mobile_mcp@latest setup-codex

Verify registration:

codex mcp get lazy-mobile-mcp

Then open a new Codex session and call mobile.list_devices.

Current local checkout:

node bin/lazy-mobile-mcp.js setup-codex --local --name lazy-mobile-mcp-local

Codex One-Command Setup (Advanced)

Optional overrides:

npx -y lazy_mobile_mcp@latest setup-codex \
  --name lazy-mobile-mcp \
  --sqlite-path "$HOME/.codex/mcp-data/lazy-mobile/mobile.db" \
  --adb-bin adb \
  --wda-base-url http://127.0.0.1:8100 \
  --device-allowlist emulator-5554 \
  --approval-policy high

Local checkout with the same overrides:

node bin/lazy-mobile-mcp.js setup-codex \
  --local \
  --name lazy-mobile-mcp-local \
  --sqlite-path "$HOME/.codex/mcp-data/lazy-mobile/mobile.db" \
  --adb-bin adb

Run with npx:

npx -y lazy_mobile_mcp@latest

Global install:

npm install -g lazy_mobile_mcp
lazy-mobile-mcp

Run

Development:

npm run dev

Production:

npm run build
npm start

Configuration

• SQLITE_PATH (default artifacts/mobile.db)

• ARTIFACTS_DIR (default: parent directory of SQLITE_PATH; screenshots live in screenshots/)

• DEVICE_ALLOWLIST (comma-separated)

• MOBILE_APPROVAL_POLICY (off|high|medium, default off)

• LOG_LEVEL (debug|info|warn|error)

• ADB_BIN (default adb)

• WDA_BASE_URL (optional override for iOS WDA endpoint)

• DEVICE_LIST_TTL_MS (default 10000)

• WORKER_TIMEOUT_MS (default 30000)

If WDA_BASE_URL is not set, the adapter probes common local endpoints (127.0.0.1 / localhost, ports 8100/8101/8200/8201 + local listening ports) and caches discoveries briefly.

Security Model

lazy-mobile-mcp is a local-first MCP server. It runs over stdio with the permissions of the local OS user that starts it; it is not a hardened OS or container sandbox.

Current runtime controls:

• DEVICE_ALLOWLIST can restrict operations to known device IDs.

• All tool inputs are schema-validated before adapter execution.

• Tool attempts are recorded in SQLite audit_logs with trace_id, tool name, risk level, device ID, and result code.

• MOBILE_APPROVAL_POLICY=high requires confirm=true and a non-empty reason for high-risk tools (tap, swipe, input_text, launch_app, stop_app, press_key, open_url).

• MOBILE_APPROVAL_POLICY=medium also requires confirmation for medium-risk tools (screenshot, dump_ui, start_perf_session).

The confirm / reason fields are caller confirmation fields. They do not prove a human approved the action unless the MCP host or caller enforces a human-in-the-loop approval flow.

iOS Capability Notes

• Simulator: screenshot + launch/stop + open URL + WDA interactive actions (tap/swipe/input/dump_ui/press_key).

• Physical device: launch/stop via devicectl; screenshot and interactive actions via WDA.

• Continuous iOS cpu/memory sampling is not claimed; use one-shot launch_ms from launch_app wall-clock timing only.

• Non-macOS host: iOS tools return ERR_IOS_UNAVAILABLE_ON_HOST.

Testing

npm test

Recommended local MCP smoke:

node dist/cli.js --help
node dist/cli.js setup-codex --help

Related

• lazy-desktop-mcp — desktop computer-use MCP

• lazy-media-mcp — image/video prep for AI vision

• session-collab-mcp — multi-session collaboration MCP

License

MIT © leaf76