run-sequence-android-mcp

Maintained by Nasio Sheva. This project is a fork of android-mcp with a run_sequence tool. Existing Android tools remain available. Build with npm ci && npm run build, then configure an MCP stdio client to run node /absolute/path/to/run-sequence-android-mcp/dist/index.js.

Example tool arguments:

{"device":"DEVICE_SERIAL","steps":[{"action":"tap","x":540,"y":700},{"action":"wait","durationMs":500},{"action":"key","key":"BACK"},{"action":"wait_for_element","text":"Tasks","timeoutMs":10000}]}

To verify an interaction, add an assertion step:

{"steps":[{"action":"tap","x":540,"y":700},{"action":"assert_element","resourceId":"success_message","timeoutMs":5000},{"action":"assert_no_element","text":"Loading","timeoutMs":5000},{"action":"assert_app","packageName":"com.example.dashboard","timeoutMs":5000}]}

run_sequence also accepts variables, whose string values can be used as {{name}} in text, selectors, and assert_app:

{"variables":{"email":"user@example.com"},"steps":[{"action":"text","text":"{{email}}"}]}

Saved flows

Use android_save_flow once to persist a named sequence, then call android_run_flow with its name whenever the agent needs to repeat it. Saved flows keep default variables, which can be overridden at run time; android_run_flow also accepts the same optional record setting as run_sequence. android_list_flows shows the available flows and android_delete_flow removes one after an explicit confirm: true.

To permanently remove every saved flow and its stored variables, stop active recordings, and remove temporary MCP artifacts, call android_clear_saved_data with {"confirm": true}. Calling it without confirmation is a dry run. Only flows saved explicitly with android_save_flow persist across MCP sessions.

Flows are stored in ~/.android-mcp/flows.json by default. Set ANDROID_MCP_FLOWS_PATH to place the flow store elsewhere.

Supported actions are tap, swipe (fromX, fromY, toX, toY, durationMs), key (BACK, HOME, ENTER, TAB), wait (durationMs), text (text, optional clear and submit), wait_for_element, assert_element, assert_no_element (selector-based), and assert_app (packageName, optional activity; all assertions accept timeoutMs). Consecutive input steps run in one ADB shell; waits and assertions run on the host. Non-ASCII text is pasted through the Android clipboard when the device supports its shell command.

Related MCP server: scrcpy-mcp

Lightweight test evidence

Recording defaults are tuned for quick test evidence: 480px maximum dimension, 1.5 Mbps bitrate, and a 30-second time limit. Use record.mode: "always" to keep a video for every run, or "on_failure" to keep a video only for failures. Failed recorded runs also save a screenshot, UI hierarchy XML when available, and recent logcat in the temporary MCP directory.

{
  "steps": [{"action":"tap","x":540,"y":700},{"action":"assert_element","resourceId":"success_message","timeoutMs":5000}],
  "record": {"mode":"on_failure"}
}

To record outside a sequence, use android_start_recording. It accepts maxSize, bitRate, and timeLimit; for example {"maxSize":480,"bitRate":1500000,"timeLimit":30}. android_pause_recording finalizes the current MP4 segment and android_resume_recording starts the next one in the same session. Android's native screenrecord has no true pause support, so the session manifest lists each segment instead of pretending they are one continuous video. To create a combined file when ffmpeg is installed, pass mergeTo to android_stop_recording.

For organized evidence across multiple scenarios, call android_start_test_run first and pass its id as record.testRunId. android_capture_checkpoint saves a screenshot, UI XML when available, and logcat; android_finish_test_run finalizes the manifest. A sequence may alternatively set record.testName to create an implicit run, and record.capture to "before_after" or "on_assertion_failure" for automatic checkpoints.

// android_start_test_run
{"name":"checkout-regression"}

// run_sequence, using the returned test-run id
{
  "steps":[{"action":"tap","x":540,"y":700},{"action":"assert_element","resourceId":"order_confirmed","timeoutMs":5000}],
  "record":{"mode":"on_failure","testRunId":"test-run-...","capture":"on_assertion_failure"}
}

For a manual recording session, call android_start_recording, android_pause_recording, android_resume_recording, then android_stop_recording. The final call returns every segment and the manifest; add mergeTo when ffmpeg is installed and a combined MP4 is needed.

An MCP (Model Context Protocol) server that gives AI agents full control of Android devices and emulators through plain ADB — no companion APK, no extra daemon, no telemetry.

With this server, agents like Claude Code, Claude Desktop, or Cursor can see the screen (screenshots + UI hierarchy) and act on it (tap, swipe, type, launch apps, read logs, record video) on any device that adb can reach.

You: "Open Settings, turn on dark mode, and show me a screenshot"
Agent: launches the app, navigates by reading the UI hierarchy,
       taps the right elements, and returns a screenshot — hands-free.

Why another Android MCP?

This project merges the best ideas of two excellent servers into one dependency-light TypeScript implementation:

Differences by design:

• ADB only. No uiautomator2 server APK on the device, no mobilecli binary on the host.

• Zero telemetry. Nothing is phoned home, ever.

• Android-first. No iOS code paths to carry around.

• Agent-friendly errors. Failures return actionable messages that tell the agent what to try next.

Requirements

• Node.js 18+

• Android platform-tools (adb) — auto-detected from ANDROID_HOME, ~/Library/Android/sdk (macOS), or %LOCALAPPDATA%\Android\Sdk (Windows), with PATH as fallback

• An Android device with USB debugging or wireless debugging enabled, or a running emulator

Installation

git clone https://github.com/nasiosheva/run-sequence-android-mcp.git
cd run-sequence-android-mcp
npm install
npm run build

Claude Code

claude mcp add run-sequence-android -- node /path/to/run-sequence-android-mcp/dist/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["/path/to/run-sequence-android-mcp/dist/index.js"]
    }
  }
}

Cursor / other MCP clients

Any client that speaks MCP over stdio works the same way: run node /path/to/run-sequence-android-mcp/dist/index.js as the server command.

Environment variables (all optional)

Device selection

Every tool accepts an optional device parameter. When omitted, the server resolves the target in this order:

1. ANDROID_MCP_DEVICE environment variable

2. The only online device, if exactly one is connected

3. The first physical device (USB or WiFi preferred over emulators)

android_list_devices also auto-connects wireless-debugging peers advertised via mDNS (adb mdns services) when the device list is empty — devices on the same network appear without any manual adb connect.

Capabilities — 41 tools

Test automation

Device management

App management

Screen observation

Interaction

System

Element selectors

android_tap_element and android_wait_for_element accept any combination of:

Usage examples

Prompts you can give an agent once the server is connected:

• "List my devices and take a screenshot of the current screen."

• "Open the Settings app and toggle dark mode."

• "Install ~/Downloads/app-release.apk with all permissions granted, launch it, and check logcat for errors."

• "Fill in the login form: tap the field with resource id email, type user@example.com, then tap the Login button."

• "Record the screen while you walk through the onboarding flow, then save the video to my desktop."

• "My Flutter app crashed — read the crash buffer and tell me why."

How it works (spec)

┌──────────────┐   stdio (JSON-RPC / MCP)   ┌─────────────┐   adb CLI   ┌─────────────┐
│  MCP client   │ ◄────────────────────────► │ android-mcp │ ◄─────────► │   device /  │
│ (Claude, ...) │                            │  (Node.js)  │             │   emulator  │
└──────────────┘                            └─────────────┘             └─────────────┘

• Transport: stdio, stateless — one server process per client session.

• Screenshots: adb exec-out screencap -p, returned as PNG (inline base64 image or file).

• UI hierarchy: adb exec-out uiautomator dump /dev/tty, parsed with fast-xml-parser, retried up to 10× when the bridge returns a null root. Elements with no size or no useful text/id are filtered out.

• Input: adb shell input (tap/swipe/text/keyevent/draganddrop). ASCII text uses input text; non-ASCII text is set with cmd clipboard set and pasted with KEYCODE_PASTE when supported by the device.

• Recording: adb shell screenrecord is spawned in the background at 480px/1.5 Mbps by default. Stop sends SIGINT to the on-device process (killall -2 screenrecord), waits for the file to finalize, then adb pulls it. Pause/resume is implemented as finalized MP4 segments recorded in a session manifest, because Android does not provide native pause/resume. run_sequence can control recording and checkpoint capture automatically.

• Foreground app detection: dumpsys activity activities (ResumedActivity, covering both pre- and post-Android-13 formats) with dumpsys window (mFocusedApp) as fallback.

• Safety rails: package names validated against [a-zA-Z0-9_.], output paths must be absolute with allowed extensions, URLs restricted to http(s) unless explicitly overridden.

Project layout

src/
├── index.ts    entry point — stdio transport
├── server.ts   MCP server + 41 tool registrations
├── adb.ts      adb discovery/execution, device resolution, WiFi + mDNS connect
└── ui.ts       uiautomator dump parsing, selector matching, wait-for-element

Development

npm run watch      # rebuild on change
npm run inspector  # test tools interactively with MCP Inspector
npm test           # lifecycle regression tests without a connected Android device

Troubleshooting

Contributing

Issues and pull requests are welcome. Keep changes small and focused:

1. Fork and create a feature branch.

2. npm run build must pass with no TypeScript errors.

3. Verify against a real device or emulator where possible (MCP Inspector makes this easy).

4. Describe the behavior change in the PR.

License

MIT. This fork is maintained by Nasio Sheva (@nasiosheva); the original copyright notice is retained in the license.