adb-mcp-server

ADB over MCP. Drive an Android device over the network from any MCP-compatible agent.

What problem this solves

You have an Android device — phone, tablet, e-reader — that you want an LLM agent to operate. The other ADB MCP servers on GitHub assume the device is plugged into the same machine the agent runs on. That doesn't work if the agent lives on a server (a droplet, a CI runner, a home-lab box) and the device is somewhere else on the network.

This server is built for that network-first case. The device is reachable at <host>:5555 over Wi-Fi, Tailscale, a VPN — anything routable. The design follows from that:

• No tool-call races. All ADB calls go through a single queue, so parallel agent calls don't trample each other.
• No screencap loops. Captures are rate-limited to one per 10 seconds.
• Classified errors. The agent can tell "device offline" from "ADB unauthorized" from "host unreachable", and recover differently.
• Path allowlists on push/install. adb_push and adb_install reject sources outside configured prefixes, with traversal-resistant checks.

How to use it

Claude Desktop / Claude Code

// e.g. ~/.config/claude/mcp.json
{
  "mcpServers": {
    "adb": {
      "command": "npx",
      "args": ["-y", "@sfaizi24/adb-mcp-server"],
      "env": { "ADB_HOST": "192.168.1.42" }
    }
  }
}

OpenClaw

# plugins.entries.acpx.config.mcpServers
adb:
  command: npx
  args: ["-y", "@sfaizi24/adb-mcp-server"]
  env:
    ADB_HOST: "100.64.0.5"

Manual / dev

git clone https://github.com/sfaizi24/adb-mcp-server.git
cd adb-mcp-server
npm install
ADB_HOST=192.168.1.42 node index.js

Tools

• adb_status — Connection check + device info (model, Android version, SDK level).
• adb_shell — Run a shell command. Output truncated at 100KB.
• adb_screencap — Capture the screen as PNG, saved to a temp file on the host. Rate-limited to 1 per 10s.
• adb_ui_dump — Structured JSON dump of the UI hierarchy, with computed centerpoints for taps. Filters: clickable_only, with_text_only, include_raw_xml.
• adb_install — Install an APK. Reinstalls allowed; downgrades blocked. Source path allowlisted.
• adb_push — Push a file from host to device. Source path allowlisted.
• adb_pull — Pull a file from device to host. Default destination is /tmp/.
• adb_input — Simulate input: tap (x, y), swipe (x1, y1, x2, y2, duration_ms?), keyevent (code), text (value).

Requirements

• Node 18+
• adb on PATH, or set ADB_BIN to its absolute path
  • macOS: brew install android-platform-tools
  • Linux: apt install android-tools-adb, or download the SDK platform-tools archive
  • Windows: download platform-tools, add the directory to PATH
• A target Android device with ADB over TCP enabled (see below)

Enabling ADB over TCP on the device

One-time setup:

1. Connect the device to a host via USB.
2. On the device: enable Developer Options, then USB debugging.
3. Approve the host's ADB key when prompted.
4. On the host: adb tcpip 5555.
5. Unplug. The device now accepts ADB at <device-ip>:5555.

Find the device's IP under Settings → About → Status, or in the Wi-Fi details. On Tailscale, use the Tailscale IP.

ADB over TCP usually does not survive reboot. Re-plug and run adb tcpip 5555 again to re-enable.

Configuration

| Variable | Required | Default | Purpose | | --- | --- | --- | --- | | ADB_HOST | yes | — | Device hostname or IP. 192.168.1.42, 100.64.0.5 (Tailscale), phone.local (mDNS), etc. | | ADB_PORT | no | 5555 | ADB TCP port on the device. | | ADB_BIN | no | adb | Path to the adb binary if not on PATH. | | MCP_ALLOWED_PUSH_DIRS | no | /tmp/ | Comma-separated absolute prefixes that adb_push may read from. | | MCP_ALLOWED_INSTALL_DIRS | no | /tmp/ | Comma-separated absolute prefixes that adb_install may read APKs from. |

Security

• This server gives any connected agent shell access and APK install ability on the target device. Only run it on hosts where you trust the agents that can call its tools.
• Network ADB has no authentication. Anyone with network reach to <device>:5555 can connect. Restrict via firewall, Tailscale ACL, or VPN. Do not expose port 5555 to the open internet.
• adb_push and adb_install allowlist source paths (default /tmp/). The check resolves paths first (path.resolve), so ../ traversal does not bypass it. Symlink leaves are rejected; symlinked ancestor directories are not separately blocked — keep allowlist directories out of writable-by-untrusted-user space.

License

MIT. See LICENSE. Contributions accepted under the same terms — please run npm test before opening a PR.

Acknowledgements

Built on @modelcontextprotocol/sdk.