adbfleet-mcp

An MCP 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.

Maintained by FoxPhone, cloud Android phones. It is built on the adbfleet library.

Tools

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.

Related MCP server: mcp-android-emulator

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:

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

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

{
  "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, 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 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

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.