aiphone-mcp

MCP server for controlling Android devices via ADB. Exposes tools for screenshots, UI interaction, app management, wireless ADB, and device diagnostics.

Works with any MCP-compatible client: LM Studio, Claude Desktop, Cursor, Windsurf.

---

Features

• Screenshots with automatic compression (WebP, JPEG, PNG)
• UI inspection — tap, swipe, type, find elements by selector
• App control — launch, stop, install checks, open URLs
• Wireless ADB over TCP/IP
• Device info — battery, memory, storage, network interfaces
• Navigation — home, back, recents, screen rotation
• Notifications — post and inspect system notifications
• Connectivity — toggle WiFi, mobile data, airplane mode
• Assertions — foreground app and element presence checks
• Escape hatch — run any arbitrary adb shell command

---

Requirements

• Node.js 18+
• ADB in your PATH
• Android 8+ with USB Debugging enabled

To enable USB Debugging: Settings → About Phone → tap Build Number 7 times → Developer Options → USB Debugging.

---

Installation

npx (no install needed):

npx aiphone-mcp

Global install:

npm install -g aiphone-mcp

Local clone:

git clone <repository-url>
cd aiphone-mcp
npm install
npm link

---

Client Configuration

All clients use the same config structure. The entry point is npx aiphone-mcp.

{
  "aiphone": {
    "command": "npx",
    "args": ["aiphone-mcp"]
  }
}

---

Configuration

Variable	Default	Description
AIPHONE_ADB_PATH	adb	Path to adb binary

{
  "aiphone": {
    "command": "npx",
    "args": ["aiphone-mcp"],
    "env": {
      "AIPHONE_ADB_PATH": "/usr/local/bin/adb", 
    }
  }
}

---

Available Tools

Device

Tool	Description
list_devices	List all connected ADB device serials
get_device_info	Full hardware identity, battery, memory, storage, and network info
get_screen_size	Physical screen resolution in pixels
get_foreground_app	Package and window currently visible to the user

Screen Observation

Tool	Description
take_screenshot	Capture the screen as an optimized image (WebP by default). Supports max_width, max_height, format, and quality parameters.
get_ui_elements	Parsed list of interactive UI elements from the UIAutomator hierarchy
dump_ui_xml	Raw UIAutomator XML hierarchy string

Interaction

Tool	Description
tap	Tap at absolute screen coordinates
double_tap	Double-tap at absolute screen coordinates
tap_element	Tap the center of an element by its bounds array [x1, y1, x2, y2]
tap_by_selector	Find an element by selector and tap it
swipe	Swipe gesture — directional (up, down, left, right) or coordinate-based
type_text	Type text into the currently focused input field
type_in_element	Find an input field by selector, focus it, clear existing text, and type
press_key	Press a key by name (back, home, enter, search, delete, ...) or numeric keycode

Element Selectors

Tool	Description
find_element	Find an element by resourceId, text, contentDesc, or className
wait_for_element	Poll until a matching element appears or timeout elapses
assert_element_exists	Assert that an element matching a selector is present — returns PASS/FAIL

Navigation

Tool	Description
go_home	Press the Home button
go_back	Press the Back button
open_recents	Open the recent apps switcher
rotate_screen	Set device rotation: 0=portrait, 1=landscape, 2=reverse portrait, 3=reverse landscape
delay	Wait for a specified number of milliseconds (max 10 000)

App Control

Tool	Description
open_app	Launch an app by package name using the LAUNCHER intent
open_url	Open a URL in the device default browser
force_stop_app	Force-stop an app by package name
is_app_installed	Check whether a package is installed on the device
list_installed_apps	Return all installed package names
assert_foreground_app	Assert a package is currently in the foreground — returns PASS/FAIL

Wireless ADB

Tool	Description
enable_wireless_adb	Switch a USB-connected device to TCP/IP mode (run before disconnecting USB)
get_device_ip	Return all active network interfaces with IP addresses
adb_connect	Connect to a device over TCP/IP at a given IP and port
adb_disconnect	Disconnect a wireless ADB target, or all wireless devices if no target is specified

Notifications

Tool	Description
post_notification	Post a system notification (bigtext, inbox, or media style)
dump_notifications	Return raw dumpsys notification output — active notifications and history

Connectivity

Tool	Description
set_wifi	Enable or disable WiFi
set_mobile_data	Enable or disable mobile data
set_airplane_mode	Enable or disable airplane mode

Escape Hatch

Tool	Description
adb_shell	Run any arbitrary adb shell command — use when no other tool covers the action

---

Screenshot Parameters

Parameter	Type	Default	Description
max_width	integer	1080	Max width in pixels (downscales proportionally)
max_height	integer	1920	Max height in pixels (downscales proportionally)
format	string	webp	webp, jpeg, or png
quality	integer	75	Compression quality 1–100 (ignored for PNG)

Images are never upscaled.

---

Selectors

Tools that locate elements accept a selector object with these fields:

Field	Match	Example
resourceId	Exact	"com.example.app:id/search_bar"
text	Substring	"Sign in"
contentDesc	Substring	"Close button"
className	Exact	"android.widget.EditText"
clickableOnly	Filter	true

Priority: resourceId > text > contentDesc > className.

---

Troubleshooting

No devices found — check that USB Debugging is enabled and the device is authorized. Run adb devices to verify.

adb not found — make sure adb is in your PATH, or set AIPHONE_ADB_PATH to the full binary path.

Wireless connection fails — both machines must be on the same network. Run enable_wireless_adb while USB is still connected, get the IP with get_device_ip, then call adb_connect.

Screenshot too large — use max_width: 720, format: "webp" to reduce output size.

---

License

MIT. See LICENSE for the full text.