androir-mcp
This server provides an MCP interface to control and automate Android devices (real or emulated) via ADB and UIAutomator, enabling AI agents to see the screen, read UI elements, and perform interactions — no device-side app required.
Device Management
List connected devices (
list_targets) — serial numbers, state, and modelGet detailed device info (
status) — state, system properties, and battery level
Screen Reading
Capture a screenshot (
screenshot) — returns the current screen as a PNG imageDescribe the screen (
describe_screen) — parses the live UIAutomator UI tree into a flat list of elements with labels and exact tap coordinates (x, y)
Input & Interaction
Tap at specific screen coordinates (
tap)Swipe from one coordinate to another with optional duration (
swipe)Long press at a coordinate with optional duration (
long_press)Type arbitrary text including spaces, special characters, and unicode (
type_text)
Key Events
Press named keys like home, back, enter, or recents (
press_key,press_home,press_back)
App & URL Launch
Launch an app by package name or friendly name (
launch_app)Open any HTTP/HTTPS URL in the device's default browser (
open_url)
All tools accept an optional
serialparameter to target a specific device when multiple are connected.describe_screenreturns exact element coordinates that feed directly intotap, enabling deterministic interactions without OCR guessing.
Allows AI agents to control physical Android devices and emulators via adb, providing tools for screen capture, UI tree inspection, input events (tap, swipe, type), app launching, and device status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@androir-mcp what's on the screen?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
androir-mcp
Drive real Android devices from any AI agent — see the screen, tap, swipe, type, over adb.
An independent, standalone Model Context Protocol server
that gives an AI agent a clean, safe automation surface for physical Android
devices and emulators: capture the screen, read the live UI tree, and drive
input — backed entirely by adb + uiautomator, no native code and no
device-side app.
Requiresadb (Android platform-tools) and an Android device with USB
debugging enabled (or an emulator). The server runs locally, holds no
credentials, and talks only to the device(s) adb already sees.
✨ What is androir-mcp?
androir-mcp is a standalone MCP server for automating Android over adb. It
is its own project — not a copy or port of anything — exposing a small,
conventional screen-read + input tool set that drops into any MCP-based agent
loop.
Everything is backed by adb and uiautomator: there is no native code and
nothing to install on the device. The agent shells out to adb (always as an
argv array — never a shell string) to capture screenshots, dump the UI
hierarchy, and send input events.
The key advantage on Android is that describe_screen returns the real UI
tree — exact element bounds and text straight from uiautomator — rather
than guessing from OCR. Tap coordinates come back as element centers and feed
straight into tap, so an agent can read a screen and act on it deterministically.
Related MCP server: Android MCP Server
🚀 Features
📸
screenshot— capture the device screen as a PNG (signature-validated).🌳
describe_screen— parse theuiautomatorUI tree into a flat list of labels with center tap coordinates (text / content-desc / class, entity-decoded).👆
tap/swipe/long_press— coordinate input in device pixels.⌨️
type_text— type arbitrary text safely (spaces, metacharacters, and unicode all type verbatim).🔘
press_key/press_home/press_back— named key events.📱
launch_app— launch by package name or a friendly name (resolved from the installed package list, cached per device).🔗
open_url— open anhttp(s)URL in the default browser.🔎
list_targets/status— enumerate connected devices and read device state, properties, and battery.
Safety by construction:
🛡️ argv-only adb — every command is an argument array, never a shell string, and any value handed to the device shell is single-quoted for it, so there is no shell-injection surface.
✅ strict serial validation — serials are checked against
[A-Za-z0-9.:_-](≤ 128 chars) before reaching any subprocess.⏱️ per-call timeout (default 30 s) with process-group kill on timeout.
🤫 scrubbed errors — concise messages only; no raw
adbstderr (which can leak serials/paths) and no host stack traces reach the model.
🛠️ Tools
Tool | adb implementation | Returns |
|
| serials + model + state |
|
| device/offline/unauthorized + info |
|
| PNG image content |
|
| element list: label / center tap (x,y) |
|
| confirmation |
|
| confirmation |
|
| confirmation |
|
| confirmation |
|
| confirmation |
|
| confirmation |
|
| confirmation |
| resolve name→package (from | confirmation |
|
| confirmation |
All tools take an optional serial; it defaults to the single connected device
and errors if the choice is ambiguous. Coordinates are in device pixels, so
describe_screen tap points feed straight into tap with no translation.
🏁 Getting started
Prerequisites
adb(Android platform-tools) on yourPATH.An Android device with USB debugging enabled, or a running emulator. Confirm it's visible:
adb devices
Build
npm install
npm run buildAttach to an MCP client
Add the built server to your MCP client config:
{
"mcpServers": {
"androir": {
"command": "node",
"args": ["/path/to/androir-mcp/dist/index.js"]
}
}
}Verify
With a device connected, run the self-check (it lists targets, takes a screenshot, and dumps the UI tree):
npm run selfcheckIt prints PASS when the three core tools work end-to-end against a real device.
🤖 Use with an AI agent
Once androir is attached to your MCP client, give the agent a goal and let it
read the screen and act:
You: Open the Settings app, go to Wi-Fi, and tell me which network is connected.
Agent: calls
launch_app("settings")→describe_screen()(reads the labels + tap coordinates) →tap(x, y)on "Wi-Fi" →describe_screen()again → reports the connected network.
Because describe_screen returns exact element bounds and text, the agent taps
real coordinates rather than guessing from a screenshot.
🗺️ Status & roadmap
Core tools —
screenshot,describe_screen,tap,swipe,long_press,type_text,press_key/home/back,launch_app,open_url,list_targets,statusuiautomatorXML parsing → labels + center tap coordinates (entity-decoded, malformed-XML tolerant)Device-shell-safe input escaping (no shell injection) + strict serial validation
Unit tests for the XML parser and the input-escaping logic
Pre-push secret-scan hook
Recording / replay skills
Multi-device parallel control
Emulator-specific paths
Published npm package /
npxbin
This README and roadmap fill in as the project progresses.
📄 License
Available Tools
13 toolsdescribe_screenA
Parse uiautomator UI tree; returns element labels and tap coordinates
Inputs: serial.
launch_appC
Launch app by package name or friendly name
Inputs: name (required), serial.
list_targetsA
List connected Android devices (serial, state, model)
Inputs: no named parameters.
long_pressC
Long press at (x,y)
Inputs: x (required), y (required), serial, duration.
open_urlA
Open an http(s) URL in the default browser
Inputs: url (required), serial.
press_backC
Press the back button
Inputs: serial.
press_homeB
Press the home button
Inputs: serial.
press_keyC
Press a named key (home, back, enter, recents)
Inputs: key (required), serial.
screenshotB
Capture device screen as PNG
Inputs: serial.
statusA
Device info: state, properties, battery
Inputs: serial.
swipeB
Swipe from (x1,y1) to (x2,y2)
Inputs: x1 (required), y1 (required), x2 (required), y2 (required), +2 more.
tapB
Tap at screen coordinates (device pixels)
Inputs: x (required), y (required), serial.
type_textA
Type text via adb input (spaces become %s)
Inputs: text (required), serial.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Tools are mostly distinct, but press_key overlaps with press_back and press_home, causing potential confusion about which to use. Other tools like tap, long_press, and swipe are clearly differentiated.
Most tools follow a verb_noun pattern (e.g., describe_screen, launch_app, press_back). However, 'status' and 'screenshot' deviate as single nouns, and 'long_press' is slightly awkward. Overall, the convention is fairly consistent.
13 tools cover a broad range of Android interaction tasks without being overwhelming. Each tool serves a clear purpose, and the count is well-scoped for device automation.
The tool set covers core device operations: launching apps, UI tree parsing, input simulation, and device info. Minor gaps like scrolling or clipboard access are missing but can be worked around with existing tools.
Related MCP Connectors
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
AI agents on real phones: run tasks, read the screen, tap, type and install apps.
Cloud Android phones for AI agents: create a phone, read the screen, tap, type, install APKs, park.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server that gives AI agents full vision and control over Android devices via ADB and scrcpy. Supports screenshots, input, apps, UI automation, shell, files, and clipboard.38392 npm136MIT
- FlicenseAqualityDmaintenanceAn MCP server designed for Android development, enabling AI assistants to directly control Android devices for screenshots, UI analysis, app management, and more.19-
- AlicenseAqualityDmaintenanceAn MCP server that gives AI agents full control of Android devices and emulators through plain ADB — no companion APK, no extra daemon, no telemetry.2614MIT
- AlicenseNot gradedqualityAmaintenanceAn MCP server that enables AI agents to control Android and iOS devices via natural language, using platform tools like adb and simctl.3,636 npm56Apache 2.0