adb-mcp

Everything was built by LLM's

MCP server for controlling an Android device over ADB. The host server is written in TypeScript and talks to a Kotlin helper APK that exposes semantic UI control through an AccessibilityService.

The project is optimized for a physical Android phone connected over USB ADB. Screenshots and coordinate gestures are intended as explicit fallbacks; normal actions use direct Android commands or semantic accessibility selectors.

Status

Prototype implementation. The TypeScript server builds and its unit tests pass. The Android helper requires a local Android SDK before it can be built.

Requirements

• Node.js 22 or newer
• npm
• Android SDK command-line tools or Android Studio
• A USB-connected Android device with ADB enabled

Install

npm install

Build and test

npm run build
npm test

To build the Android helper:

scripts/bootstrap-android-sdk.sh
npm run build:helper

If the Android SDK is already installed, set ANDROID_HOME or create helper/local.properties with:

sdk.dir=/absolute/path/to/Android/sdk

helper/local.properties is intentionally ignored by git.

Run

Build the server first:

npm run build
npm start

For an MCP client, copy mcp-config.example.json and replace /absolute/path/to/adb-mcp with this repository's absolute path.

Helper APK

Build and install the debug helper APK:

npm run build:helper
npm run install:helper

Then enable the helper AccessibilityService on the device once in Android settings.

Tools

The server exposes low-level Android control primitives such as:

• device discovery and setup status
• helper APK installation
• app launch and foreground app detection
• semantic tree lookup and node actions
• safe key events
• guarded shell execution
• bounded run_steps composition

See workflows/android-device-control.md for the V1 behavior contract.