io.github.dockndevai/mcp-android

mcp-android

A Model Context Protocol server to control an Android phone over ADB — the phone equivalent of the Mac-control servers. Claude can see the screen (screenshots + UI hierarchy) and tap, type, press keys, launch apps, set alarms/timers, and read notifications. Safe-by-default, with the suite's access-mode + flag model.

Runs on your computer and drives a phone connected by USB or wireless debugging (great for the Z Fold 7). It is not installed on the phone and does not need root.

iOS? A stock iPhone can't be controlled this way — Apple's sandbox forbids cross-app/system automation. See the separate mcp-ios repo for the realistic (Appium/WebDriverAgent over USB from a Mac) approach.

Quickstart

brew install android-platform-tools        # provides adb
# On the phone: Settings → Developer options → enable USB (or Wireless) debugging, then authorize this computer
adb devices                                 # confirm your device shows "device"

Run it straight from npm — no clone or build needed:

npx -y @dockndevai/mcp-android

Or add it to Claude Code in one line (start read-only):

claude mcp add android -e ANDROID_MODE="read-only" -- npx -y @dockndevai/mcp-android

See docs/CLIENTS.md for Claude Desktop, Cursor, Codex, Windsurf, and VS Code configs.

Setup from source

brew install android-platform-tools        # provides adb
adb devices                                 # confirm your device shows "device"
npm install && npm run build

Tools

Read (read-only+): list_devices, device_info, screenshot, ui_dump, current_app, list_apps, get_notifications

Write (read-write+): tap, swipe, input_text, press_key, launch_app, open_url, set_alarm, set_timer

Admin (admin): install_apk, uninstall_app, clear_app_data (need ANDROID_ALLOW_INSTALL), run_shell (needs ANDROID_ALLOW_SHELL; not registered otherwise)

The typical loop for driving the UI: screenshot → ui_dump (find bounds) → tap/input_text.

Security model

Concern	Flag	Default
What it can do	ANDROID_MODE	read-only
Which packages in scope	ANDROID_PACKAGE_ALLOWLIST	(all)
Protected packages (never uninstall/clear)	ANDROID_PROTECTED_PACKAGES	settings, systemui, gms
Allow install/uninstall/clear	ANDROID_ALLOW_INSTALL	false
Allow raw adb shell	ANDROID_ALLOW_SHELL	false
Interactive confirmation (destructive ops)	MCP elicitation (client-driven)	(on when the client supports it)
Preview without touching device	ANDROID_DRY_RUN	false
Audit log (stderr)	ANDROID_AUDIT_LOG	true

When the connected client supports MCP elicitation, destructive tools (uninstall_app, clear_app_data, install_apk, run_shell) pause and ask the human to approve the exact action before it runs — the model can't approve on your behalf. When the client can't elicit, the access-mode + flag gates above are the control.

Run with Claude Desktop / Claude Code

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

Example prompts

• "Take a screenshot of my phone and tell me what's on screen."
• "Set an alarm for 6:30am labeled Gym."
• "Open the Clock app and start a 10-minute timer."
• "What notifications do I have piling up?"

Develop

npm run dev
npm test          # security policy
npm run typecheck

License

MIT