Skip to main content
Glama

Android Phone MCP

Control authorized Android phones from an MCP-capable AI app. Install Node.js 20+; missing ADB is downloaded from Google on first use. No APK, API key, fixed computer path or device serial is required.

Requirements — read before installing

Installing this npm package alone does not give you an AI assistant or authorize a phone. You need a local MCP-capable AI app, Node.js and an Android phone with debugging permission.

On your computer

Requirement

What you need

Official download / setup

Operating system

A desktop/laptop running Windows, macOS or Linux. Automatic ADB setup supports Windows/macOS x64 or arm64 and Linux x64; Windows arm64 may need OS x64 emulation. Other architectures need their own compatible ADB.

Use a Node.js build supported by your OS; see Node.js downloads.

Node.js with npm/npx

Node.js 20 or newer is the package minimum. Prefer the current supported LTS release. Keep npm/npx available on PATH so your AI app can start the server.

Download Node.js — its standard installer includes npm/npx. Reopen your terminal and AI app after installing.

A local AI app with stdio MCP support

The app must be able to run a command on this computer and call MCP tools. For example, use Codex or VS Code with Copilot/MCP support. Sign in and satisfy that app's account/plan requirements. A browser-only client that supports remote HTTP servers alone cannot run this stdio server directly.

Codex MCP setup, or download VS Code and follow its MCP setup guide. Choose one compatible app.

Internet and storage

Internet for the initial npm package/dependency downloads and, if needed, Google's Platform Tools. Your AI app may also require internet. Allow enough disk space for Node.js, your AI app, npm dependencies and the ADB cache.

No separate service account or API key is required by this MCP package; your chosen AI app has its own requirements.

ADB / Platform Tools

Needed to communicate with Android. The package uses an existing ADB or downloads and verifies Google's official Platform Tools automatically on supported platforms. Usually no manual ADB installation or PATH edit is needed.

For offline/custom setups or unsupported architectures: official Android Platform Tools downloads. Set ADB_PATH to a compatible executable if needed.

Check Node.js and npm before installing:

node --version
npm --version
npx --version

If a command is not found, finish installing Node.js and reopen the terminal. If the AI app still cannot find npx, make sure it inherits the Node.js installation's PATH and restart the app.

On your Android phone and network

Connection

Requirements

Official instructions

Wireless, without an initial cable

Android 11+ with Wireless debugging available; enable Developer options and Wireless debugging. Keep phone and computer on the same Wi-Fi and authorize pairing on the phone. Have its current pairing code, pairing address and connection address ready.

Enable Developer options and ADB wireless pairing.

Network access

The Wi-Fi must allow the computer to communicate with the phone. Guest/corporate networks, client isolation, VPNs or firewall rules can interfere. If discovery fails, enter the phone's addresses manually; manual entry still requires network reachability.

Android device connection troubleshooting.

USB, optional alternative

A data-capable USB cable, USB debugging enabled, and the phone's debugging authorization accepted. Older Android versions can use USB subject to their ADB support.

Run apps on a hardware device.

USB drivers/permissions, only when needed

Windows may need a manufacturer-specific driver; Linux USB may need udev permissions. These are USB requirements, not requirements for wireless pairing.

Official manufacturer USB driver links and device setup for Linux.

Android Studio, Java/JDK, Python, Git, root access and an APK on the phone are not required to use this package's tools. iPhone is not supported. The AI app must be configured with the MCP entry below before it can control the phone; --doctor only checks ADB and connected devices.

Related MCP server: phone-control

Installation and wireless connection (Windows PowerShell)

Complete these three main steps in PowerShell. Replace PHONE_IP, PAIRING_PORT and CONNECTION_PORT with the current values shown on your own phone. Do not paste the PS prompt, placeholder words or trailing backslashes into the commands.

Step 1 — Install the npm package

npm install -g deepboyearn-android-mcp@latest

Requires Node.js 20+; prefer a currently supported LTS release. No ZIP extraction or Git installation is needed.

Step 2 — Check the installation and locate ADB

android-phone-mcp --doctor

This checks ADB and lists any connected phones. On supported systems, missing ADB is downloaded from Google automatically. An empty device list is normal before connecting. The doctor command does not pair a new phone.

In the same PowerShell window, save the ADB executable path reported by the doctor command:

$adb = ((android-phone-mcp --doctor | Select-String '^Installed as ' | Select-Object -First 1).Line -replace '^Installed as ', '').Trim()
if (-not $adb -or -not (Test-Path -LiteralPath $adb)) { throw 'ADB path not found. Copy the Installed as path from --doctor into $adb manually.' }

This uses the actual ADB location instead of assuming a particular Android SDK folder. If automatic detection fails, set $adb manually to the full executable path printed after Installed as. Keep using the same PowerShell window so the variable remains available.

PowerShell rule: use & $adb, not $adb alone, to execute the program. The & call operator is required when running a path stored in a variable.

Step 3 — Pair first, then connect

On an Android 11+ phone:

  1. Connect the computer and phone to the same Wi-Fi.

  2. Open Developer options → Wireless debugging and turn it on. Approve the network prompt if shown.

  3. Tap Pair device with pairing code. A popup displays a temporary six-digit code and its own IP address and port.

  4. Keep this popup open while pairing. Use the address and port from this popup in the following command:

& $adb pair PHONE_IP:PAIRING_PORT

When asked for Enter pairing code, type the current six-digit code from that still-open popup. Wait for Successfully paired to .... Codes and pairing ports can change when the popup is reopened; never copy an old code from a guide.

  1. After successful pairing, close the popup and return to the main Wireless debugging screen. Use the IP address and port shown there with:

& $adb connect PHONE_IP:CONNECTION_PORT
  1. Verify the live connection:

& $adb devices -l

Your phone must appear with status device. Then the ADB connection is ready for the MCP. A phone appearing under Paired devices only proves stored authorization; it does not prove an active connection.

Where the address appears

What it is for

Command

Pair device with pairing code popup

Temporary pairing service, with six-digit code

& $adb pair PHONE_IP:PAIRING_PORT

Main Wireless debugging screen

Debugging connection service

& $adb connect PHONE_IP:CONNECTION_PORT

The two ports are generally different. The main-screen port is valid for connect; do not use it as the pairing port. The pairing popup/code is needed only during pairing, not for keeping an already-paired connection alive. ADB may connect automatically after pairing; if devices already shows status device, a manual connect is unnecessary. Ports can change after restarting the phone, Wi-Fi or Wireless debugging.

Paired successfully, but no phone notification?

Do not use a notification as the only success check. Pairing authorizes the computer, while an active ADB connection is a separate state. Android's reference implementation shows the wireless-debugging connected notification when a Wi-Fi ADB connection becomes active; manufacturer behavior can differ. If pairing succeeded but the phone is missing from devices, run connect using the main-screen port. If devices shows status device, the connection is ready even if you do not see a notification. If it does not, a missing notification alone cannot identify the cause.

References: Android's official ADB pairing and connection guide and Android's wireless connection notification implementation.

Common connection errors

Symptom

What to check

Unexpected token 'pair' in PowerShell

Use & $adb pair ..., including the leading &.

protocol fault (couldn't read status message)

The code can be correct while the port is wrong. Reopen the pairing popup and use its current address, port and code together; leave it open until pairing finishes. Also check current Platform Tools and network reachability if it persists.

Successfully paired, but phone is not listed

Pairing is not the same as connecting. Use connect with the main Wireless debugging screen's current port.

Connection refused, offline or empty list

Recheck Wireless debugging, the current connection port, same Wi-Fi, VPN/firewall/client-isolation restrictions and device authorization. Do not keep retrying an old address.

For discovery diagnostics, while the pairing popup is open:

& $adb mdns services

Services containing _adb-tls-pairing._tcp are pairing services; _adb-tls-connect._tcp are connection services. Identify your own phone. If discovery is blocked, enter the addresses from its screens manually.

Optional — Connect with the Codex app

This command is only for adding the MCP to Codex. It is not required to pair/connect Android or to use another MCP client. The Codex CLI must already be installed and available in your terminal; see Codex MCP setup.

After the global npm installation, run:

codex mcp add android-phone -- cmd /d /c android-phone-mcp

Restart the Codex app to load the configuration, then ask it to use the android-phone MCP. Pairing the phone by itself does not configure an AI app: choose this Codex setup or configure another compatible local MCP client.

Other MCP clients / npx alternative

For a compatible local client that accepts this JSON structure:

{
  "mcpServers": {
    "android-phone": {
      "command": "npx",
      "args": [
        "--yes",
        "deepboyearn-android-mcp"
      ]
    }
  }
}

The client starts this stdio MCP automatically. There is no public HTTP server URL. Windows clients that cannot start npx directly can use command cmd and args ["/d", "/c", "npx", "--yes", "deepboyearn-android-mcp"]. Client-specific configuration formats may differ.

If you prefer not to install globally, you can check the package with:

npx --yes deepboyearn-android-mcp@latest --doctor

The npm package is deepboyearn-android-mcp. The unrelated name android-phone-mcp is not this npm package; android-phone-mcp is this package's installed executable name.

USB alternative

For USB, enable USB debugging, use a data cable and accept the phone's debugging authorization. Older Android versions can use USB subject to ADB support. Windows may need a manufacturer USB driver; Linux may need USB permissions. Owner authorization is required for every phone. This package does not automatically enable legacy unauthenticated TCP debugging.

Multiple phones

The inventory includes model, Android version, physical ID, connection aliases and authorization states. Selection lasts for this server process and follows hardware ID across connection changes. If the chosen phone goes offline, tools fail instead of switching silently. Every control tool also accepts optional device (unique ID, connection serial or unique model). Unknown hardware IDs fall back to connection IDs and may need reselection after reconnecting.

Tools

Tool

Purpose

android_discover

Find wireless pairing/connection services

android_pair / android_connect

Pair and connect an authorized phone

android_devices / android_select_device

List phones and choose one

android_info

Model, Android version, battery and display

android_screenshot / android_screen

PNG screenshot or accessible screen elements

android_tap / android_tap_element

Tap coordinates or an exact label/id

android_swipe

Scroll or swipe

android_type

Printable English/ASCII text

android_key

Navigation and editing keys

android_apps / android_open_app

List or launch apps

Automatic ADB

Existing ADB is found through PATH, ANDROID_HOME, ANDROID_SDK_ROOT or common SDK folders. Otherwise Google Platform Tools 37.0.3 is fetched from Google's official repository, verified against a pinned SHA-256 checksum and extracted to ~/.cache/android-phone-mcp. Vendor notices are retained. Downloads occur on first ADB use, not during npm install. Progress goes to stderr to preserve the MCP protocol on stdout.

Automatic setup supports Windows/macOS x64 or arm64 and Linux x64. Windows arm64 may require OS x64 emulation. Other platforms need a compatible ADB installed separately. Google's SDK terms apply to the downloaded Platform Tools; this npm package does not redistribute their binaries.

Optional environment variables:

  • ADB_PATH: explicit ADB executable; invalid explicit paths fail instead of downloading another copy.

  • ANDROID_MCP_AUTO_ADB=0: disable automatic ADB download.

  • ANDROID_MCP_CACHE_DIR: change the Platform Tools cache folder.

  • ANDROID_SERIAL / ANDROID_HARDWARE_SERIAL: optional default phone selectors. Per-call and session selections override them.

Limits and privacy

Vendor/version differences can affect features. iPhone is not supported. This is not a guarantee for every Android model. Real-device checks used one OnePlus Nord on Windows, including independently downloaded ADB. Multi-phone selection and archive verification have offline tests. CI covers supported Node versions on Windows/macOS/Linux; real macOS/Linux phones have not been tested.

The server cannot bypass lock screens, grant root or retrieve apps' original source code. Secure screens may block screenshots; games/WebViews may expose few elements. Hindi, emoji, multiline input and literal %s are rejected by typing; use the phone keyboard for those.

When Android cannot obtain an idle UI tree (for example during a playing video), android_screen returns a mode: screenshot explanation and a PNG instead of failing without a usable view. Normal accessible screens still return the JSON element array. Use coordinate taps/swipes with the fallback; label-based taps require an accessible screen. Offline/ADB errors remain errors. Secure apps can still produce black screenshots. android_open_app resolves the app's launcher and waits for Android's launch status; it does not prevent subsequent user navigation.

Screen data goes to the connected AI client and may be private. UI text is untrusted. The AI client must handle authorization for messages, purchases, deletions and account changes; the server has no human confirmation dialog. There is no arbitrary shell, file deletion, APK installation or background screenshot logging tool.

Development

npm ci
npm test
npm run smoke
node scripts/smoke.js --actions
npm pack --dry-run

Smoke tests need an authorized connected phone. The actions option opens Settings and presses Back. The npm archive includes runtime code, package metadata, README, LICENSE and example configuration. CLI options: --help, --version, --doctor, --config.

Updating documentation and installed copies

GitHub README changes appear on GitHub after pushing. They do not change an already-published npm version: maintainers must publish a new package version to update the npm package's README and included files. Users with a global installation can update using npm install --global deepboyearn-android-mcp@latest. For an npx setup, run npx --yes deepboyearn-android-mcp@latest --doctor to check the latest release; pinned versions remain unchanged until the user updates the pin.

Built with the official MCP TypeScript SDK and Android Debug Bridge. MIT license applies to this project's code.

Available Tools

15 tools
android_appsA
Read-onlyIdempotent

List installed application package IDs, optionally only user-installed apps.

Inputs: device, userOnly.

android_connectA
Destructive

Connect an already-paired phone using its CONNECTION host:port. Does not change the selected phone. Inspect android_devices afterwards.

Inputs: address (required).

android_devicesB
Read-onlyIdempotent

List physical phones with unique IDs, model, Android version, connection aliases, offline/unauthorized connections and the current selection.

Inputs: no named parameters.

android_discoverA
Read-onlyIdempotent

Discover nearby Android wireless debugging services on the same Wi-Fi. Pairing services appear while the phone pairing-code dialog is open. Discovery may be blocked; addresses can be supplied manually.

Inputs: no named parameters.

android_infoB
Read-onlyIdempotent

Read model, Android version, physical serial, display size and battery.

Inputs: device.

android_keyB
Destructive

Press a named navigation or editing key. ENTER may submit the focused form.

Inputs: key (required), device.

android_open_appA
Destructive

Resolve and launch an installed app in the current Android user, waiting for Android launch status. Use android_apps to find package names. Later user interaction may change the foreground app.

Inputs: packageName (required), device.

android_pairA
Destructive

Pair a user-authorized Android 11+ phone using the current six-digit Wireless debugging code and PAIRING address. The connection address usually has a different port. Never guess codes. Then use android_connect.

Inputs: code (required), address (required).

android_screenA
Read-onlyIdempotent

Read accessible screen elements, labels and coordinates. If Android cannot read an animated/protected screen or exposes no elements, returns a mode:screenshot explanation and PNG for coordinate control. Normal results remain a JSON array.

Inputs: device.

android_screenshotB
Read-onlyIdempotent

Capture the current display as a PNG image. Secure app screens may appear black.

Inputs: device.

android_select_deviceA
Destructive

Choose the default phone for this server session by unique id, exact connection serial or unique model from android_devices. Selection follows hardware id across connection changes and never switches silently if that phone goes offline.

Inputs: selector (required).

android_swipeC
Destructive

Swipe or scroll between display coordinates.

Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more.

android_tapB
Destructive

Tap a screen coordinate. Inspect the screen first.

Inputs: x (required), y (required), device.

android_tap_elementA
Destructive

Tap one enabled element identified by exact text, content description or resource ID. Fails if ambiguous; inspect screen and use coordinates.

Inputs: field (required), match (required), device.

android_typeA
Destructive

Type printable ASCII into the focused field. Hindi, emoji, newlines and literal %s are unsupported. Does not press Send or Enter.

Inputs: text (required), device.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation4/5

    Each tool maps to a distinct step in the phone-control lifecycle, and descriptions explicitly differentiate easily-confused pairs (discover vs devices, pair vs connect, tap vs tap_element). The only real blur is android_screen vs android_screenshot, since android_screen can fall back to returning a PNG, but the descriptions call this out clearly.

    Naming Consistency4/5

    All tools share the android_ prefix and use snake_case, which makes the set highly predictable. However, the verbs are mixed: some are actions (tap, swipe, connect, pair) while others are bare nouns (info, screenshot, screen, apps), so the verb_noun pattern is not fully uniform.

    Tool Count5/5

    15 tools is well within a healthy range and each one earns its place: discovery, pairing, connection, selection, inspection, input and app launching are all separate concerns. There is no obvious padding or redundant capability.

    Completeness4/5

    The surface covers the full connection lifecycle plus core interaction (screen read, screenshot, tap, tap_element, swipe, type, key, apps, launch). Minor gaps remain: no disconnect/unpair, no long-press or drag gestures, no shell/notification/file operations, and typing is limited to ASCII.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to control Android devices via ADB, providing tools for screen capture, tap/swipe/input, app management, and diagnostics. Works locally over USB or WiFi and integrates with MCP clients like Claude and Cursor.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables controlling an Android device from an MCP client via ADB, including wireless debugging discovery, UI-tree inspection, and performing taps, swipes, typing, app actions, and shell commands without relying on screen coordinates.
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to control a physical Android device or Docker-hosted emulator over ADB by taking screenshots and performing taps, swipes, key presses, text input, shell commands, app launches, and device info queries. It runs as a local MCP stdio server alongside a web UI and REST API for remote access.
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP-compatible AI assistants to see and control Android devices through screenshots, taps, swipes, typing, app management, UI inspection, file transfer, shell commands, and audio/video streaming. It connects over ADB with optional low-latency acceleration for faster input and near-instant screenshots.
      392 npm
      MIT