mcp-android-adb

This MCP server provides a mobile device control surface via ADB, enabling remote management of Android devices. It exposes a range of tools for application management, screen control, input and gesture actions, device information retrieval, and a general shell command interface. When running, you can install and uninstall apps, launch and terminate apps, unlock or lock the screen, simulate taps and keystrokes, perform swipe gestures, capture screen information (including a description via the visual model), and run arbitrary shell commands on the device. The visual model capabilities (controlled by VISUAL_MODEL_ON and related env vars) allow you to obtain richer context like screenshot descriptions, which can assist in validating UI states during automated workflows.

Prerequisites:

• A Go development environment installed on your machine
• Git installed to clone the repository
• Access to the machine or server where you will run the MCP server

Step-by-step:

1. Clone the repository:

git clone https://github.com/github-hewei/mcp-android-adb-server.git
cd mcp-android-adb-server

2. Build the server:

go build

3. Run the server (example, adjust path if needed):

# If you built a binary named mcp-android-adb-server (default go build)
./mcp-android-adb-server

4. Optional: configure via mcp_config in your MCP manager by adding the server entry with the provided command path and environment variables as shown in the README example. Ensure you have ADB access to the target device and, if using visual model features, provide valid API keys and base URL in env vars.

Tips and caveats:

• DEVICE_ID is required to target the correct Android device; obtain it via adb devices before starting the server.
• If the device has a lock screen, you may need to supply SCREEN_LOCK_PASSWORD to unlock during automation.
• VISUAL_MODEL_ON enables the optional visual-description feature; you must supply VISUAL_MODEL_API_KEY, VISUAL_MODEL_BASE_URL, and VISUAL_MODEL_NAME to use it.
• Ensure the Android device is accessible over ADB from the host running the MCP server (ADB server running, proper USB/wireless connection, and authorized device).
• If you encounter connectivity or permission errors, verify that the executable path is correct and that the host has permission to run it.
• When using the visual model, be mindful of API usage limits and latency, as image description retrieval may introduce delays in workflows.