# adbfleet-mcp

An [MCP](https://modelcontextprotocol.io/) server that lets an AI assistant work with **many Android devices over ADB at the same time**. It can list devices, connect network endpoints, check device health, install APKs and, if you allow it, run shell commands. Every action runs in parallel across the devices you pick and returns results per device.

It works with **any device `adb` can reach**: USB phones, emulators, Wi-Fi debugging, ADB-over-TCP boxes, and cloud phones such as [FoxPhone](https://www.foxphone.com/).

Maintained by [FoxPhone](https://www.foxphone.com/), cloud Android phones. It is built on the [adbfleet](https://github.com/foxphone/adbfleet-js) library.

<!-- mcp-name: io.github.foxphone/adbfleet-mcp -->

## Tools

| Tool | What it does | Enabled by default |
|---|---|---|
| `list_devices` | Lists attached devices with serial, state, kind (usb/emulator/network), model, `@index`, and the name and tags from your inventory. | yes (read-only) |
| `device_health` | Model, Android version, battery, temperature, free space on `/data`, uptime and screen size for each device. | yes (read-only) |
| `connect_devices` | Runs `adb connect` on `host[:port]` endpoints in parallel, with retries. The port defaults to 5555. | yes |
| `disconnect_devices` | Runs `adb disconnect` on endpoints. | yes |
| `install_apk_on_devices` | Installs an APK, or a set of split APKs, from the machine running the server. Supports `-r`, `-g` and `-d`. A device counts as failed when adb prints `Failure [...]`, even if adb exits 0. | yes (`--no-install` turns it off) |
| `run_shell_on_devices` | Runs one non-interactive `adb shell` command on each selected device. | **no**: start the server with `--allow-shell` |

### Safety defaults

- **Shell is off unless you turn it on.** `run_shell_on_devices` isn't registered until you start the server with `--allow-shell` or set `ADBFLEET_MCP_ALLOW_SHELL=1`.
- **Device selection must be explicit.** Tools that act on devices need either `serials` (serials, inventory names, serial prefixes or `@N`) or `all_devices: true`. If neither is given, nothing runs.
- **Timeouts on everything.** Each device has a timeout (30 s by default, `--timeout`), and requested timeouts are capped by `--max-timeout`, 600 s by default. When a command times out, its adb process is killed.
- **Limits.** `--max-devices` (default 50) rejects calls that target too many devices. Output for each device is truncated at `--max-output` characters.
- **APK checks.** Files must exist and end in `.apk`. `--apk-dir DIR` limits installs to files inside one folder.
- **No credentials and no vendor APIs.** The server only calls the standard `adb` binary.

## Requirements

- Node.js 18 or newer
- Android platform-tools (`adb`). The server looks for it at `$ADBFLEET_ADB`, then `$ANDROID_HOME/platform-tools`, then on your `PATH`.

## Setup

Claude Desktop, Cursor, or any MCP client that uses the `mcpServers` format:

```json
{
  "mcpServers": {
    "adbfleet": {
      "command": "npx",
      "args": ["-y", "adbfleet-mcp"]
    }
  }
}
```

To turn on shell commands and limit APK installs to one folder:

```json
{
  "mcpServers": {
    "adbfleet": {
      "command": "npx",
      "args": ["-y", "adbfleet-mcp", "--allow-shell", "--apk-dir", "/home/me/builds"],
      "env": { "ADBFLEET_ADB": "/opt/android-sdk/platform-tools/adb" }
    }
  }
}
```

### Options

```
--allow-shell        expose run_shell_on_devices (off by default; or ADBFLEET_MCP_ALLOW_SHELL=1)
--no-install         do not expose install_apk_on_devices
--apk-dir DIR        only allow installing APKs from inside DIR
--timeout SEC        default per-device timeout (30)
--max-timeout SEC    upper limit for any requested timeout (600)
--jobs N             devices handled in parallel (8)
--max-devices N      refuse calls that target more devices than this (50)
--max-output N       truncate per-device stdout/stderr to N chars (16000)
--inventory FILE     adbfleet fleet.json with device names and tags
```

The server reads the same `fleet.json` inventory as the [adbfleet CLI](https://github.com/foxphone/adbfleet-js), from `--inventory`, `$ADBFLEET_INVENTORY`, `./fleet.json` or `~/.config/adbfleet/fleet.json`. That lets the assistant refer to devices by name, for example `"serials": ["cloud-01"]`.

## Using it with FoxPhone cloud phones

[FoxPhone](https://www.foxphone.com/) cloud phones are Android devices that run in the cloud. When ADB access is enabled, each one has a `host:port` endpoint, and from there it works like any other network device. Here is a typical conversation with your assistant:

1. *"Connect my cloud phones 203.0.113.10:5555 and 203.0.113.11:5555."* The assistant calls `connect_devices`.
2. *"Which devices are online, and do any have less than 1 GB free?"* The assistant calls `list_devices` and then `device_health`.
3. *"Install /home/me/builds/app-release.apk on all of them."* The assistant calls `install_apk_on_devices` with `all_devices: true`.
4. With `--allow-shell` on: *"Open com.example.app on the cloud phones."* The assistant calls `run_shell_on_devices` with `monkey -p com.example.app -c android.intent.category.LAUNCHER 1`.

The addresses above are documentation examples, so replace them with the endpoints shown for your devices. The same steps work with any ADB-over-TCP device or provider.

## Development

```bash
npm install
npm test        # node:test with an in-memory MCP client and a mocked adb (no devices needed)
```

## License

MIT © Foxphone LLC. See [LICENSE](LICENSE).