moreplay

Let an AI assistant use your Android phone. It can read the screen, tap, type and scroll, and once it has done a task, you can save the steps and replay them later without the AI.

moreplay is an MCP server: a plugin that gives AI apps such as Claude Code, Codex, Cursor, VS Code or Gemini CLI new tools. This one gives them an Android phone.

• Fast. Reading the screen takes about 50 ms, not the usual 3 seconds.

• Cheap on tokens. A screen is 1-2 KB of text, and the tools add only ~850 tokens to each request.

• Record once, replay for free. Save what the AI did as a small YAML file and run it again with one command, no AI needed. Handy for repeating manual tests.

Quick start

1. What you need

• A computer with Node.js 20 or newer.

• adb, the tool that talks to Android phones:

  • macOS: brew install android-platform-tools

  • Windows / Linux: download SDK Platform-Tools and add the folder to your PATH.

• An Android phone (Android 8 or newer) and a USB cable. An emulator works too.

2. Turn on USB debugging

1. On the phone, open Settings > About phone and tap Build number seven times. This unlocks Developer options.

2. Open Developer options and turn on USB debugging.

   • Xiaomi, Redmi and POCO phones: also turn on USB debugging (Security settings), or taps will not work.

3. Plug the phone in and tap Allow on the "Allow USB debugging?" prompt.

3. Check that it works

npx -y moreplay doctor

This checks adb, your phone, and the moreplay agent. It taps nothing. Lines with ✓ are fine; a ✗ comes with a hint on how to fix it.

4. Add it to your AI app

Any app that supports MCP can use moreplay. Pick yours:

Claude Code, Codex CLI: one command.

claude mcp add moreplay -- npx -y moreplay
codex mcp add moreplay -- npx -y moreplay

claude mcp add only adds it for the folder you run it in. Run it in the folder you open Claude Code in, or add --scope user to have it everywhere.

Claude Desktop, Cursor, Windsurf, Gemini CLI, Cline and most other apps: add this to the app's MCP config file.

{
  "mcpServers": {
    "moreplay": {
      "command": "npx",
      "args": ["-y", "moreplay"]
    }
  }
}

VS Code (GitHub Copilot): uses servers instead of mcpServers. Put this in .vscode/mcp.json, then use Copilot Chat in Agent mode:

{
  "servers": {
    "moreplay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "moreplay"]
    }
  }
}

Restart the app, and you are done.

npx, or install it? The configs above use npx, which downloads moreplay the first time and needs no install step. You can install it instead:

With a global install, use "command": "moreplay", "args": [] in the config (or claude mcp add moreplay -- moreplay). If you use nvm, desktop apps may not see its PATH; give the full path from which moreplay instead. In a project, npx moreplay ... picks the installed version, with no download.

5. Try it

Ask your assistant things like:

• "What is on my phone screen right now?"

• "Open Settings and turn on dark mode."

• "Open the Clock app and set a timer for 5 minutes."

• "Log in to my app with test@example.com, then save the steps as a flow called login."

Already have another phone tool, like mobile-mcp? Name the one you want, so the assistant does not pick the other:

• "Use moreplay to open Settings and turn on dark mode."

• "With moreplay, check what is on the screen and save a screenshot to ./shots/home.jpg."

Only one of them can control the phone at a time. If moreplay says another tool holds the connection, turn the other MCP server off in your AI app's MCP settings (in Claude Code: /mcp), or ask the assistant to stop using it.

Nothing is installed on the phone. A small agent (17 KB) is copied to /data/local/tmp and runs only while your AI app is using moreplay.

Related MCP server: android-mcp

Replay without the AI

Ask the assistant to record a task ("start recording a flow called login"), let it do the task, then ask it to save the flow. You get a file like .moreplay/flows/login.yaml (or wherever you ask it to save).

Passwords and PINs stay out of the file: give them as variables when recording ("record a flow called login with the variable pin = 482913"), and the saved flow says ${pin} wherever the value was typed. Pass the real value again when you replay it.

name: login
dismiss: [Not now]             # tapped away whenever it shows up (ads, prompts)
steps:
  - launch: com.example.app
  - tap: Sign in
  - type: {field: Email, value: "${email}"}
  - wait_for: Home
  - screenshot: login-ok

You can also write or edit these files by hand. Run one from the terminal:

npx moreplay run login --var email=test@example.com

RUN  .moreplay/flows/login.yaml  5 steps

  ✓ launch com.example.app         234 ms
  ✓ tap "Sign in"                  148 ms
  ✓ type "${email}" into "Email"   390 ms
  ✓ wait_for "Home"                812 ms
  ✓ screenshot login-ok            170 ms

PASS  5 steps in 2.1 s
Evidence  .moreplay/evidence/login/20261027-123950

Each step waits for its button or text to appear, so there are no fixed sleeps. The command exits with 0 when every step passed and 1 when one failed, so it works in CI too. Screenshots are saved in .moreplay/evidence/<flow>/<time>/ (or pass --evidence <folder>). Commit the flows you want to keep, and add .moreplay/evidence/ to your .gitignore.

A folder runs as a suite: every .yaml directly in it, by name (subfolders such as shared/ hold subflows and are not run on their own). Tag flows with tags: [smoke] to pick some:

npx moreplay run e2e/mobile --include-tags smoke --var pin=$PIN --junit reports/mobile.xml

--junit writes a report CI systems read (GitHub Actions, GitLab, Jenkins). When a step fails, a screenshot and the screen as text are saved next to the run's evidence (failed-step-N.jpg, failed-step-N.txt), and the report points at them.

If a step breaks after the app changes, ask the assistant to run the flow. It sees which step failed and the screen at that moment, and can fix that step for you.

Flows can reuse each other and handle screens that only sometimes appear:

steps:
  - run_flow: {file: shared/enter-pin.yaml, vars: {PROMPT: "Enter your PIN"}}
  - run_flow:
      when: {visible: "Rate this app"}
      steps:
        - tap: "Not now"

Maestro

Already using Maestro? Flows convert both ways:

npx moreplay export login > login.maestro.yaml
npx moreplay import checkout.maestro.yaml --out .moreplay/flows/checkout.yaml

Steps that have no equivalent on the other side are listed, never dropped silently.

Tools

What your AI app gets:

The full reference for people is in docs/reference: steps, selectors, flows and the command line.

How fast

Reading the screen is ~40x faster than mobile-mcp and ~70x faster than uiautomator dump, and the model reads ~9x less, both per screen and in tool definitions on every request.

Measured on one phone (Android 14, HyperOS), home screen, October 2026. Both MCP servers were timed end to end from an MCP client on the laptop. Method and raw numbers: spike/RESULTS.md.

Speed (lower is better)

What the model reads

¹ mobilecli 1.0.21, mobile-mcp's device layer, timed per CLI call. mobilecli also keeps an on-device server, but it waits for the screen to settle (up to 2 s) before every read. Plain adb means uiautomator dump, input tap and screencap.

Troubleshooting

Run npx -y moreplay doctor first; it names most problems.

• No device found, or the device is "unauthorized": unplug and replug the phone, then tap Allow on the USB debugging prompt. If no prompt shows, turn USB debugging off and on again.

• Taps do nothing on a Xiaomi, Redmi or POCO phone: turn on USB debugging (Security settings) in Developer options, then reboot the phone.

• "another tool holds the UiAutomation connection": only one automation tool can control the phone at a time. Close Appium, Maestro, uiautomator2 or mobile-mcp first.

• Several phones connected: pick one with ANDROID_SERIAL=<serial> (see adb devices).

Contributing

Bug reports from more phones are the most useful thing right now; please include the model and Android version. To build from source, see CONTRIBUTING.md. docs/architecture.md explains how it works, and docs/roadmap.md lists what is next.

License

MIT