# 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

```sh
npm install
```

## Build and test

```sh
npm run build
npm test
```

To build the Android helper:

```sh
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:

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

`helper/local.properties` is intentionally ignored by git.

## Run

Build the server first:

```sh
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:

```sh
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.