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, and collect baseline metrics (cpu, memory, launch time) with session history in SQLite.

Keywords: MCP server, mobile automation, Android ADB automation, iOS simulator automation, WebDriverAgent, 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: @wilsonbeam/openclaw-adb-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.

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

• WDA endpoint auto-discovery for iOS interactive actions.

• Risk-tiered approval policy for interactive actions.

• JSON logging and unified error contract.

• SQLite persistence for sessions, perf_samples, artifacts, audit_logs.

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

• mobile.stop_perf_session

• mobile.get_perf_samples

Architecture

• TypeScript MCP server + worker (tool contracts, validation, policy, trace ID)

• Android adapter (adb)

• iOS adapter (simctl, devicectl, WDA)

• SQLite storage (artifacts/mobile.db)

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)

• 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)

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

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 tap, swipe, input_text, launch_app, and stop_app.

• MOBILE_APPROVAL_POLICY=medium also requires confirmation for screenshot and 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 + WDA interactive actions.

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

• 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