AI-Native Android Automation

QApilot MCP CLI
User Guide

Automate real Android devices and emulators by talking to Claude, Cursor, or any MCP-compatible AI client. Describe test flows in plain English — no Appium code required.

Android + AppiumLocal device & emulatorClaude · Cursor · Codex

Install

Prerequisites

Make sure all five are in place before installing.

Node.js 18+

Download from nodejs.org or use nvm.

Java JDK 11+

Required by Appium. Set JAVA_HOME in your shell profile.

Android SDK / Studio

Installs adb and platform-tools. Set ANDROID_HOME to the SDK path.

Device or Emulator

USB device with USB Debugging on, or an AVD emulator. Verify with adb devices.

Appium 2.19.0

Install globally and add the UIAutomator2 driver. See the Appium Setup section for exact commands.

Install the CLI

Install QApilot MCP globally from the distribution package:

bash

npm install -g https://api.qapilot.io/internal/qapilot-mobile-mcp.tgz

Verify the install:

bash

npx qapilot-mcp --stdio
# Server starts and waits for input — no errors = success

Appium Setup

One-time setup — install Appium and its Android driver with the pinned versions below, then start the server.

bash — one-time setup

# Step 1 — Install Appium
npm i --location=global appium@2.19.0

# Step 2 — Install the UiAutomator2 Android driver
appium driver install uiautomator2@4.2.6

# Step 3 — Start Appium (run this every time before testing)
appium --allow-insecure chromedriver_autodownload,adb_shell \
       --base-path /wd/hub \
       --allow-cors

# Step 4 — Confirm device is visible
adb devices
# → emulator-5554   device

Use the exact versions shown — other Appium or driver versions may break the MCP server. Keep Appium running in a separate terminal before starting any test session.

Configure Your AI Client

QApilot MCP connects via the Model Context Protocol. Paste the config for your client:

Open Claude → Settings → Developer → Edit Config and add the block below inside your existing mcpServers object:

claude_desktop_config.json

{
  "mcpServers": {
    "qapilot-mobile-mcp": {
      "command": "npx",
      "args": ["-y", "qapilot-mcp", "--stdio"],
      "env": {}
    }
  }
}

command + args

Runs the CLI via npx — no separate install needed

Restart your AI client after saving. QApilot Mobile MCP will appear in the connected tools list.

Register & Login

Create a QApilot account

Ask your AI to register you — an activation email is sent automatically.

Sample prompt

Sign me up for QApilot with email alice@example.com

QApilot sends an activation link to your email. Click it to activate — your login credentials arrive by email. Use them to log in on the next step.

Log in

If env credentials are set in your config, Claude logs in automatically on first use.

With env credentials set

Log in to QApilot

Without env credentials

Log in to QApilot as alice@example.com with password MyPass123

Launch your app

Provide the Android package ID. The default project and device are selected automatically.

Sample prompt

Launch the CarWale app — package ID is com.carwale.android

All-in-one session start

Start a QApilot session and open com.carwale.android on the local emulator

Recording Test Steps

Once the app is launched, describe what you want to test. The AI builds a structured plan and executes each step on the device in real time.

Search flow

Tap Search, type "Honda City", select the first result, and verify the car detail page loads

Log in with email user@test.com and password Test@123, then screenshot the home screen

Navigation + assertion

Go to Compare, add two cars, and confirm the Compare button is visible

Scroll and filter

Scroll down on the Filters page, select Petrol as fuel type, and apply the filter

Form submission

Fill the enquiry form: name "John", phone "9999999999", city "Hyderabad", then submit

Step titles are generated automatically (max 50 chars, no XPath) — reports and the dashboard always stay readable.

Live Preview

Watch the device screen in your browser as steps execute.

Get preview link

Give me the live preview URL for this session

During execution

Open the preview so I can watch the test run

The preview URL is returned automatically on every mobile_launch_app call — click it before the first step starts to watch from the beginning.

Accepting Steps

After a successful run, push the recorded steps to QApilot as a saved test case for future replay.

Sample prompt

Steps look good — accept them and push to QApilot

With a test case name

Accept these steps as "Search and select Honda City" in QApilot

Only the happy-path steps are saved (failures excluded). If a step failed, fix it first, generate a passed report, then accept.

Executing Saved Test Cases

Replay any test cases saved in your QApilot project — one by one, in batch, or from an Excel sheet.

List available test cases

Sample prompt

Show all test cases in the CarWale Android project

Run by ID or batch

Single test

Run test case TC-101 on the connected emulator

Multiple tests

Execute test cases TC-101, TC-102, and TC-105 in sequence

Run from an Excel sheet

Sample prompt

Run all test cases from regression_suite.xlsx

Check status

Sample prompt

What's the current execution status?

Reports

Generate a report at the end of every session. Reports include step results, screenshots, errors, and timing.

Passed session

Generate a passed report for this session

Failed session

Generate a failed report — the login button wasn't found at step 3

HTML report

Save an HTML report to ~/Downloads/test-results.html

Reports are saved to ~/Downloads/qapilotmcpreport/qapilot/<date>/<sessionId>/ — includes output.json, report.yaml, and on pass a scenario.feature Gherkin file.

Always generate a report at the end of every session, even on failure — it clears execution state so the next test can start cleanly.

⚙

All MCP Tools

Every capability the server exposes:

Tool	What it does
mobile_signup	Register a new QApilot account; triggers activation email
mobile_login	Log in; uses env credentials automatically when set
mobile_logout	Clear the current auth token
mobile_start_session	One-shot: login + project + device + launch app
mobile_list_projects	List projects in your QApilot workspace
mobile_select_project	Set the active project for this session
mobile_list_available_devices	List connected local Android devices and emulators
mobile_use_device	Select a specific device when multiple are connected
mobile_list_apps	List installed apps on the connected device
mobile_launch_app	Launch an app by package ID; starts Appium session
mobile_stop_appium_session	End the current Appium session cleanly
mobile_submit_plan	Submit a structured test plan for execution
mobile_execute_plan	Run the submitted plan on the device
mobile_execute	Perform a single manual action (tap, type, swipe…)
mobile_get_execution_state	Real-time status of the running execution
mobile_check_session_status	Check whether the Appium session is alive
mobile_get_session_info	Device capabilities and session metadata
mobile_get_preview_url	Get the live screenshot stream URL
mobile_accept_steps	Push happy-path steps to QApilot as a test case
mobile_execute_testcases	Replay saved test cases by ID
mobile_run_excel_testcases	Run test cases from an Excel (.xlsx) file
mobile_generate_report	Generate output.json + report.yaml; clears execution state
mobile_get_cache_context	Fetch cached XPaths and skills for this app
mobile_cache_summary	Show what is cached for a given package
mobile_get_usage	Token and API usage for the current session

Ready to run tests from your editor?

Join the QApilot MCP early access list. Local device, your agent, a report it can read.

Request Access

QApilot MCP CLIUser Guide

Prerequisites

Node.js 18+

Java JDK 11+

Android SDK / Studio

Device or Emulator

Appium 2.19.0

Install the CLI

Appium Setup

Configure Your AI Client

Register & Login

Create a QApilot account

Log in

Launch your app

Recording Test Steps

Live Preview

Accepting Steps

Executing Saved Test Cases

List available test cases

Run by ID or batch

Run from an Excel sheet

Check status

Reports

All MCP Tools

Ready to run tests from your editor?

QApilot MCP CLI
User Guide