adb-visual-mcp
Control Android devices/emulators through adb with pure visual I/O and input, leaving visual reasoning to the caller.
List connected adb devices with readiness and model information.
Run arbitrary adb commands, global or device-scoped, with optional timeout and output capping.
Capture full-screen screenshots as JSON geometry plus PNG, optionally with a visual grid overlay.
Tap absolute screen coordinates; right/middle buttons map to long press, with configurable count.
Scroll or drag/swipe between absolute coordinates with configurable duration.
Type ASCII text, press a key, or send hotkey/key sequences to the focused app.
Optionally target a specific device serial; otherwise require exactly one ready device.
Stay stateless: no cached device selection, screen state, accessibility tree, OCR, Appium, or UI model.
Provides pure-visual control of Android devices and emulators through adb, exposing tools for listing devices, capturing screenshots with optional grid overlays, tapping and long-pressing coordinates, scrolling and swiping, typing text and sending key events, plus a raw adb_command escape hatch for arbitrary commands like installing APKs or querying properties.
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., "@adb-visual-mcp screenshot the emulator, then tap at 540, 1200"
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.
adb-visual-mcp
A small, stateless, pure-visual MCP server for Android devices. It exposes only the I/O needed to operate an emulator or phone: screen capture, taps, swipes, and keyboard input. Visual reasoning stays in the calling agent.
The server talks to Android through adb shell and adb exec-out; it does not use the accessibility tree, OCR, Appium, or a cached UI model.
Tools
devices()lists devices and readiness.adb_command(args, device?, timeout_s?, max_output_chars?)runs any adb command and returns exit code, stdout, and stderr.screenshot(device?, grid_rows?, grid_cols?)returns JSON geometry plus a PNG. The optional grid is only a visual reference overlay.click(x, y, device?, button?, count?)taps absolute screen coordinates. Right and middle map to a long press.mouse(action, device?, ...)supportsscrollanddrag(swipe).keyboard(action, device?, text?, keys?)types text or sends Android key events.
The visual and input tools accept an optional device serial. With no argument, exactly one ready device must be present. The server never caches the selected device or current screen.
adb_command is the escape hatch for everything the typed tools do not cover (installing APKs, reading properties, package management). Its args is either an argument list or a single string that is split like a shell line. Without device it runs without -s, so global commands such as devices and version work. Output is capped per stream; long output keeps the head and tail and reports how many characters were dropped.
{
"args": ["shell", "pm", "list", "packages"],
"device": "emulator-5554",
"timeout_s": 30,
"max_output_chars": 20000
}Related MCP server: scrcpy-mcp
Install
Requires Python 3.10+, adb, and a running Android device or emulator.
uv sync
uv run adb-visual-mcp --versionSet the adb path when it is not on PATH:
export ADB_VISUAL_MCP_ADB=/data/zqf/android-sdk/platform-tools/adb
export ADB_VISUAL_MCP_DEVICE=emulator-5554Run
stdio, for an MCP client that launches the process:
uv run adb-visual-mcpStreamable HTTP:
uv run adb-visual-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcpInteraction model
screenshot -> visual reasoning -> click/mouse/keyboard -> screenshot to verifyThe server does not identify buttons or choose coordinates. Callers should use a grid overlay when fine positioning is needed and should not invent coordinates for visually uncertain targets.
Notes
keyboard type uses adb shell input text; it is intended for ASCII text. For non-ASCII input, use the device's own IME or a dedicated helper app. mouse move is intentionally unsupported because Android touchscreens have no hover pointer.
Development
uv run pytest
uv run python tests/smoke.pyInstall from .deb
Release packages are attached to GitHub releases:
adb-visual-mcp_<version>_amd64.debfor a normal Linux hostadb-visual-mcp-wsl_<version>_amd64.debfor WSL2, reusing the Windows adb server
sudo apt install ./adb-visual-mcp_<version>_amd64.debThe package installs a systemd service and starts it on port 8799 at
/mcp. See docs/INSTALL.md for the WSL2 bridge, the
configuration file at /etc/adb-visual-mcp/env, and how to disable or move
the service.
WSL2 bridge (Windows USB device)
On WSL2 the reliable path is to let Windows own the USB device and reuse its
adb server from WSL, instead of attaching USB through usbipd:
C:\Users\<you>\pt-win\platform-tools\adb.exe devices -lThen install adb-visual-mcp-wsl in WSL and run:
adb-visual-mcp-wsl-check
sudo systemctl enable --now adb-visual-mcpThe launcher sets ADB_SERVER_SOCKET=tcp:127.0.0.1:5037, so 127.0.0.1
inside WSL must reach the Windows loopback (mirrored networking). Override
ADB_SERVER_SOCKET or ADB_VISUAL_MCP_ADB in /etc/adb-visual-mcp/env if
needed.
Build the packages
./packaging/build-deb.sh
ls dist/*.debThe script creates a self-contained venv with uv and packs it into the
.deb, so installation does not need network access. Use
REBUILD_VENV=1 to rebuild the venv and VERSION=x.y.z to override the
version.
Available Tools
6 toolsadb_commandA
Run an arbitrary adb command and return exit code, stdout, and stderr.
args is the adb argument list, for example ["shell", "getprop",
"ro.product.model"] or "shell pm list packages". Without device the
command runs without -s, so global commands such as devices or
version work; pass a serial for device-scoped commands.
Inputs: args (required), device, timeout_s, max_output_chars.
clickB
Tap an absolute screen coordinate. Right/middle map to a long press.
Inputs: x (required), y (required), count, button, +1 more.
devicesA
List Android devices known to adb, including readiness and model.
Inputs: no named parameters.
keyboardC
Type text, press one key, or send a key sequence to the focused app.
Inputs: action (required), keys, text, device.
mouseC
Scroll the screen or drag between absolute coordinates.
Inputs: action (required), x, y, to_x, +4 more.
screenshotC
Capture the full Android screen, optionally with a uniform visual grid.
Inputs: device, grid_cols, grid_rows.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct interaction (keyboard input, mouse scroll/drag, click tap, screenshot capture, device listing), so selection is generally clear. The main overlap is `adb_command`, a generic escape hatch that can replicate every other tool's function (e.g. `shell input tap`, `shell screencap`, `devices`), though this is an intentional, documented fallback rather than true ambiguity.
Five tools are single lowercase words (keyboard, mouse, devices, screenshot, click) while `adb_command` uses a snake_case namespace prefix, and the set mixes nouns (devices, screenshot) with a verb (click) and input-device names (keyboard, mouse). It is readable and loosely noun-oriented, but there is no predictable verb_noun or resource pattern an agent can rely on.
Six tools is well-scoped for a focused Android-device-control server: discovery, three input primitives, capture, and a raw escape hatch. Each tool earns its place without redundant wrappers or an oversized surface.
The surface covers the core interaction loop (find device, see screen, tap/drag/scroll, type) and `adb_command` closes arbitrary gaps like app install, UI hierarchy dumps, or device connect/restart. Minor gaps remain: no dedicated swipe/fling or long-press tool, and no built-in wait-for-UI or clipboard operations, though all are reachable through `adb_command`.
Maintenance
Related MCP Connectors
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Disposable cloud Android emulators for coding agents: run an APK or PR build, tap, type, screenshot.
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
- AlicenseAqualityCmaintenanceEnables AI agents to control, inspect, and automate Android devices, Waydroid containers, and AVD emulators over ADB. Provides tools for screenshots, UI-hierarchy text-based tapping, gestures, key presses, text input, app management, and raw shell commands.12MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to visually perceive and directly control Android devices via ADB and screen-control tooling, including screenshots, taps, swipes, typing, app management, UI inspection, file transfer, shell commands, and audio/video streaming.392 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to see and control Android devices through ADB and scrcpy, supporting screenshots, input, app management, UI automation, shell/file access, and audio/video streaming.392 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to see and control Android devices via ADB and scrcpy, supporting screenshots, taps, swipes, typing, app and UI automation, file transfer, shell commands, clipboard, and audio/video streaming.392 npmMIT