android-mcp

An MCP (Model Context Protocol) server that gives AI agents full control of Android devices and emulators through plain ADB — no companion APK, no extra daemon, no telemetry.

With this server, agents like Claude Code, Claude Desktop, or Cursor can see the screen (screenshots + UI hierarchy) and act on it (tap, swipe, type, launch apps, read logs, record video) on any device that adb can reach.

You: "Open Settings, turn on dark mode, and show me a screenshot"
Agent: launches the app, navigates by reading the UI hierarchy,
       taps the right elements, and returns a screenshot — hands-free.

Why another Android MCP?

This project merges the best ideas of two excellent servers into one dependency-light TypeScript implementation:

| Inspiration | What was adopted | |---|---| | mobile-mcp | App management, uiautomator-based element listing, screenshots, screen recording, orientation control | | Android-MCP | WiFi ADB + mDNS auto-discovery, selector-based taps, wait-for-element, smart default-device selection |

Differences by design:

• ADB only. No uiautomator2 server APK on the device, no mobilecli binary on the host.
• Zero telemetry. Nothing is phoned home, ever.
• Android-first. No iOS code paths to carry around.
• Agent-friendly errors. Failures return actionable messages that tell the agent what to try next.

Requirements

• Node.js 18+
• Android platform-tools (adb) — auto-detected from ANDROID_HOME, ~/Library/Android/sdk (macOS), or %LOCALAPPDATA%\Android\Sdk (Windows), with PATH as fallback
• An Android device with USB debugging or wireless debugging enabled, or a running emulator

Installation

git clone https://github.com/qalvinahmad/android-mcp.git
cd android-mcp
npm install
npm run build

Claude Code

claude mcp add android -- node /path/to/android-mcp/dist/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["/path/to/android-mcp/dist/index.js"]
    }
  }
}

Cursor / other MCP clients

Any client that speaks MCP over stdio works the same way: run node /path/to/android-mcp/dist/index.js as the server command.

Environment variables (all optional)

| Variable | Purpose | |---|---| | ANDROID_MCP_DEVICE | Default device id used when a tool call omits device | | ANDROID_MCP_ALLOW_UNSAFE_URLS | Set to 1 to allow non-http(s) URLs (e.g. deep links) in android_open_url | | ANDROID_HOME | Android SDK location, used to locate adb |

Device selection

Every tool accepts an optional device parameter. When omitted, the server resolves the target in this order:

1. ANDROID_MCP_DEVICE environment variable
2. The only online device, if exactly one is connected
3. The first physical device (USB or WiFi preferred over emulators)

android_list_devices also auto-connects wireless-debugging peers advertised via mDNS (adb mdns services) when the device list is empty — devices on the same network appear without any manual adb connect.

Capabilities — 26 tools

Device management

| Tool | Description | Key parameters | |---|---|---| | android_list_devices | List connected devices with name, Android version, connection type (usb/wifi/emulator), and state. Auto-discovers mDNS wireless peers. | — | | android_connect_wifi | Connect over WiFi ADB. Port defaults to 5555. | host | | android_device_info | Model, Android version, SDK level, screen size, orientation, battery level, foreground app. | device? |

App management

| Tool | Description | Key parameters | |---|---|---| | android_list_apps | List installed apps that have a launcher activity. | device? | | android_launch_app | Launch an app by package name. | packageName | | android_terminate_app | Force-stop a running app. | packageName | | android_install_app | Install an APK, optionally granting all runtime permissions. | apkPath, grantPermissions? | | android_uninstall_app | Uninstall an app. | packageName |

Screen observation

| Tool | Description | Key parameters | |---|---|---| | android_take_screenshot | Screenshot returned inline as an image the agent can see. | device? | | android_save_screenshot | Screenshot saved to a local .png file. | saveTo | | android_list_elements | UI hierarchy: element type, text, accessibility label, resource id, focus/clickable state, and center tap coordinates. | device? | | android_wait_for_element | Poll until an element appears — use instead of fixed sleeps for dynamic content. | selector, timeout? |

Interaction

| Tool | Description | Key parameters | |---|---|---| | android_tap | Tap at pixel coordinates. | x, y | | android_tap_element | Find an element by selector and tap its center. Waits up to timeout (default 5 s) for it to appear. | selector, index?, timeout? | | android_double_tap | Double-tap at coordinates. | x, y | | android_long_press | Long-press at coordinates. | x, y, duration? | | android_swipe | Directional swipe from screen center or from given coordinates. | direction, x?, y?, distance?, duration? | | android_drag | Drag and drop between two points. | fromX, fromY, toX, toY, duration? | | android_type_text | Type into the focused field (ASCII), optionally clearing it first and/or submitting with ENTER. | text, submit?, clear? | | android_press_key | Press a key: BACK, HOME, ENTER, APP_SWITCH, VOLUME_UP, any KEYCODE_* name, or a numeric keycode. | key | | android_open_url | Open an http(s) URL in the default browser. | url | | android_open_notifications | Expand the notification shade. | device? |

System

| Tool | Description | Key parameters | |---|---|---| | android_set_orientation | Force portrait/landscape (disables auto-rotate). | orientation | | android_start_recording | Start background screen recording (max 180 s, Android limit). | timeLimit? | | android_stop_recording | Stop recording, pull the .mp4 to this computer. | saveTo? | | android_logcat | Read recent logs with buffer selection (main/system/crash/events/all) and substring filter. Great for debugging Flutter/React Native crashes. | lines?, buffer?, filter? |

Element selectors

android_tap_element and android_wait_for_element accept any combination of:

| Selector | Matching | |---|---| | text | Exact visible text | | textContains | Substring of visible text, case-insensitive | | resourceId | Full id (com.app:id/btn_login) or short id (btn_login, auto-expanded using the foreground app package) | | contentDesc | Substring of accessibility label, case-insensitive | | className | Full class (android.widget.Button) or suffix (Button) |

Usage examples

Prompts you can give an agent once the server is connected:

• "List my devices and take a screenshot of the current screen."
• "Open the Settings app and toggle dark mode."
• "Install ~/Downloads/app-release.apk with all permissions granted, launch it, and check logcat for errors."
• "Fill in the login form: tap the field with resource id email, type user@example.com, then tap the Login button."
• "Record the screen while you walk through the onboarding flow, then save the video to my desktop."
• "My Flutter app crashed — read the crash buffer and tell me why."

How it works (spec)

┌──────────────┐   stdio (JSON-RPC / MCP)   ┌─────────────┐   adb CLI   ┌─────────────┐
│  MCP client   │ ◄────────────────────────► │ android-mcp │ ◄─────────► │   device /  │
│ (Claude, ...) │                            │  (Node.js)  │             │   emulator  │
└──────────────┘                            └─────────────┘             └─────────────┘

• Transport: stdio, stateless — one server process per client session.
• Screenshots: adb exec-out screencap -p, returned as PNG (inline base64 image or file).
• UI hierarchy: adb exec-out uiautomator dump /dev/tty, parsed with fast-xml-parser, retried up to 10× when the bridge returns a null root. Elements with no size or no useful text/id are filtered out.
• Input: adb shell input (tap/swipe/text/keyevent/draganddrop). Text is shell-escaped; only ASCII is supported by input text, and non-ASCII input returns an actionable error instead of typing garbage.
• Recording: adb shell screenrecord spawned in the background; stop sends SIGINT to the on-device process (killall -2 screenrecord), waits for the file to finalize, then adb pulls it.
• Foreground app detection: dumpsys activity activities (ResumedActivity, covering both pre- and post-Android-13 formats) with dumpsys window (mFocusedApp) as fallback.
• Safety rails: package names validated against [a-zA-Z0-9_.], output paths must be absolute with allowed extensions, URLs restricted to http(s) unless explicitly overridden.

Project layout

src/
├── index.ts    entry point — stdio transport
├── server.ts   MCP server + 26 tool registrations
├── adb.ts      adb discovery/execution, device resolution, WiFi + mDNS connect
└── ui.ts       uiautomator dump parsing, selector matching, wait-for-element

Development

npm run watch      # rebuild on change
npm run inspector  # test tools interactively with MCP Inspector

Troubleshooting

| Symptom | Fix | |---|---| | adb not found | Install Android platform-tools and/or set ANDROID_HOME. | | No Android devices connected | Enable USB debugging (or wireless debugging), accept the RSA prompt on the device, check adb devices. | | Screenshot is black | The screen is off — send android_press_key with WAKEUP first. | | Failed to dump UI hierarchy | The foreground screen is secure (password field, DRM). Use android_take_screenshot instead. | | Non-ASCII text fails | adb shell input text is ASCII-only. Type the ASCII portion or use the device keyboard. | | WiFi connect fails | Ensure wireless debugging or adb tcpip 5555 is active and the host is reachable. |

Contributing

Issues and pull requests are welcome. Keep changes small and focused:

1. Fork and create a feature branch.
2. npm run build must pass with no TypeScript errors.
3. Verify against a real device or emulator where possible (MCP Inspector makes this easy).
4. Describe the behavior change in the PR.

License

MIT © Alvin Ahmad (@qalvinahmad)