Skip to main content
Glama

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?, ...) supports scroll and drag (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 --version

Set 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-5554

Run

stdio, for an MCP client that launches the process:

uv run adb-visual-mcp

Streamable HTTP:

uv run adb-visual-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

Interaction model

screenshot -> visual reasoning -> click/mouse/keyboard -> screenshot to verify

The 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.py

Install from .deb

Release packages are attached to GitHub releases:

  • adb-visual-mcp_<version>_amd64.deb for a normal Linux host

  • adb-visual-mcp-wsl_<version>_amd64.deb for WSL2, reusing the Windows adb server

sudo apt install ./adb-visual-mcp_<version>_amd64.deb

The 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 -l

Then install adb-visual-mcp-wsl in WSL and run:

adb-visual-mcp-wsl-check
sudo systemctl enable --now adb-visual-mcp

The 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/*.deb

The 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 tools
adb_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

    B3.2/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      12
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT