android-mcp

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:

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)

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

App management

Screen observation

Interaction

System

Element selectors

android_tap_element and android_wait_for_element accept any combination of:

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 [email protected], 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

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)