android-mcp-beta

Clean-room reimplementation of Android-MCP: an MCP server that lets an AI agent operate an Android device over ADB.

It needs only adb. Nothing is installed on the device, and there is no dependency on uiautomator2.

Run

Requires Python 3.13 and adb (Android platform-tools).

uv run android-mcp-beta

The server speaks MCP on stdio. In a client's config:

{
  "mcpServers": {
    "android-mcp-beta": {
      "command": "uv",
      "args": ["--directory", "D:/Projects/android-mcp-beta", "run", "android-mcp-beta"]
    }
  }
}

The device is connected on the first tool call, so the server starts whether or not one is attached yet.

Choosing the device

With no options it uses the first physical device, or an emulator when there is none.

Option	Environment	Meaning
--device SERIAL	ANDROID_MCP_DEVICE	A serial, or host:port for a device on the network
--connection auto|usb|wifi (alias --transport)	ANDROID_MCP_CONNECTION	How to pick when no device is named
--wifi [HOST]	ANDROID_MCP_HOST	ADB over Wi-Fi; HOST or HOST:PORT, port 5555 by default
--usb [SERIAL]		ADB over USB, optionally a specific serial

Options win over the environment. Other variables:

• ANDROID_MCP_ADB_PATH names the adb binary. Otherwise adb is looked for on PATH, then in ANDROID_HOME, ANDROID_SDK_ROOT and the default Android Studio SDK folders.
• SCREENSHOT_QUANTIZED=true reduces screenshots to 256 colours, which makes them smaller.

Tools

Tool	Does
ListDevices, ConnectDevice, Device	List, choose, or disconnect the device
Snapshot	The interactive elements, each with a label and tap coordinates. use_vision adds a screenshot with the labels drawn on it; use_annotation=false leaves it clean
Click, LongClick, Swipe, Drag	Touch input by coordinates
ClickBySelector	Tap an element found by text, resourceId, className or description (exact match; resourceId may be the part after the slash), with index for the nth match
Type	Type into a field. x and y tap it first; clear empties it first. Other scripts and emoji need the optional ADBKeyboard app (below)
Press	A button: back, home, recent, volume up, enter, and so on
Notification	Pull down the notification shade
Wait, WaitForElement	Pause, or wait for an element to appear

Typing other scripts (optional)

Type uses adb shell input text, so on its own it types printable ASCII and the accented Latin letters Android can compose (é ñ ü ÿ and 107 others, not ç ß å ø). A newline presses Enter and a tab presses Tab. For anything else (CJK, Cyrillic, Arabic, emoji, ç), install the ADBKeyboard app on the device once:

adb install keyboardservice-debug.apk

Download it from the releases page. This project does not bundle it: ADBKeyboard is GPL-2.0, and it is only ever talked to over broadcasts. I tested v2.5-dev (SHA-256 41a8a099…46fbbb) on Android 15.

With it installed, text that input text cannot type is sent through it automatically. For about a second the device's keyboard is switched to ADBKeyboard, which shows no keyboard of its own, and then the keyboard that was active before is put back (and ADBKeyboard is disabled again if it was not enabled). A text field must be focused, or the call fails with an error saying so. If a crash ever leaves the device on ADBKeyboard, adb shell ime reset restores the default. Without the app, such text is rejected before anything is sent, with these instructions in the error.

Other limits

• Busy screens. The element list comes from uiautomator dump, which gives up when the screen never goes idle (a video, a running timer). Snapshot with use_vision then returns the screenshot alone and says so; click by coordinates still works.
• Drag needs Android 8 or later. Clearing a field uses input keycombination, which needs Android 12; older devices fall back to a slower method that clears up to 200 characters.

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .

The tests need no device. Layers, bottom to top: android_mcp.adb (talks to adb), android_mcp.tree (reads the screen), android_mcp.mobile (one connected device: state and actions), android_mcp.server (the MCP tools and the choice of device).