Allows AI agents to control Android devices via ADB to take screenshots, interact with the UI, launch apps, and manage notifications.
Also known as dockndevai/mcp-android, @dockndevai/mcp-android
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 189
- Latest version
- 0.1.0
- Last commit
- Nov 11, 2026
- License
- MIT
What is android MCP?
android allows AI agents to control Android devices via ADB to take screenshots, interact with the UI, launch apps, and manage notifications.
Summary generated from the project's README
About android MCP server
Controlling an Android device through an AI agent is possible with this MCP server. It allows developers to connect a phone via USB or wireless debugging to an AI client like Claude Desktop or Claude Code. By using the Android Debug Bridge, the server enables an agent to see the screen through screenshots and UI dumps, then interact with the interface by tapping, swiping, or typing text.
Users can configure different access levels using the ANDROID_MODE environment variable, ranging from read-only to read-write or admin. The server includes specific tools for managing the device, such as launching apps, setting alarms, reading notifications, and installing APKs. Security is managed through a flag-based model that protects system packages and can require human approval for destructive actions like clearing app data or running shell commands.
This setup runs locally on your computer and does not require root access on the mobile device. It is designed for developers who want to automate mobile workflows or test app interfaces using natural language instructions.
What you can do with it
- 1Visual interface inspectionAn AI agent can examine the current screen and UI hierarchy to understand what is displayed.
- 2Notification monitoringA developer can ask the AI to check for any unread or pending notifications on the device.
Written from the project's README. Every use case is checked against a quote from it.
How to install android MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall android MCP in Claude Code
$ claude mcp add mcp-android -- npx -y @dockndevai/mcp-androidInstall android MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-android": {
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-android"
]
}
}
}Install android MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-android": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-android"
]
}
}
}Install android MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-android","type":"stdio","command":"npx","args":["-y","@dockndevai/mcp-android"]}'Install android MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-android": {
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-android"
]
}
}
}Install android MCP in Codex
$ codex mcp add mcp-android -- npx -y @dockndevai/mcp-androidInstall android MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-android] command = "npx" args = ["-y", "@dockndevai/mcp-android"]
Install android MCP in Gemini CLI
$ gemini mcp add -s user mcp-android npx -- -y @dockndevai/mcp-androidInstall android MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-android": {
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-android"
]
}
}
}Configuration
ANDROID_ADB_PATHPath to the adb binary (default: adb on PATH).
ANDROID_ALLOW_INSTALLEnable install_apk / uninstall_app / clear_app_data (requires admin mode too).
ANDROID_ALLOW_SHELLEnable run_shell (arbitrary adb shell; requires admin mode too).
ANDROID_AUDIT_LOGEmit a JSON audit line to stderr per guarded operation (default true).
ANDROID_DRY_RUNValidate + log write/admin actions without executing them on the device.
ANDROID_MODEAccess mode: read-only | read-write | admin.
ANDROID_PACKAGE_ALLOWLISTComma-separated package allowlist for launch/uninstall/clear. Empty = all.
ANDROID_PROTECTED_PACKAGESPackages that can be launched/inspected but never uninstalled or data-cleared.
ANDROID_SERIALTarget device serial from `adb devices`. Empty = the only connected device.
ANDROID_TIMEOUT_MSPer-command adb timeout in milliseconds.
| Name | Description | |
|---|---|---|
| ANDROID_ADB_PATH | Path to the adb binary (default: adb on PATH). | |
| ANDROID_ALLOW_INSTALL | Enable install_apk / uninstall_app / clear_app_data (requires admin mode too). | |
| ANDROID_ALLOW_SHELL | Enable run_shell (arbitrary adb shell; requires admin mode too). | |
| ANDROID_AUDIT_LOG | Emit a JSON audit line to stderr per guarded operation (default true). | |
| ANDROID_DRY_RUN | Validate + log write/admin actions without executing them on the device. | |
| ANDROID_MODE | Access mode: read-only | read-write | admin. | |
| ANDROID_PACKAGE_ALLOWLIST | Comma-separated package allowlist for launch/uninstall/clear. Empty = all. | |
| ANDROID_PROTECTED_PACKAGES | Packages that can be launched/inspected but never uninstalled or data-cleared. | |
| ANDROID_SERIAL | Target device serial from `adb devices`. Empty = the only connected device. | |
| ANDROID_TIMEOUT_MS | Per-command adb timeout in milliseconds. |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledockndevai/mcp-android is public and reachablegithub.com/dockndevai/mcp-android ↗Pass
- Package names this repository as its source@dockndevai/mcp-android names dockndevai/mcp-android as sourcenpmjs.com/package/@dockndevai/mcp-android ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @dockndevai/mcp-androidnpmjs.com/package/@dockndevai/mcp-android/v/0.1.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/dockndevai/mcp-android ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @dockndevai/mcp-androidPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-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 |
Extra open_url schemes (beyond http, https, tel, mailto, geo, market) |
ANDROID_EXTRA_URL_SCHEMES |
(none) |
| Interactive confirmation (destructive ops) | MCP elicitation (client-driven) | (on when the client supports it) |
| Require a human | ANDROID_REQUIRE_HUMAN_APPROVAL |
false |
| 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. The prompt shows the tool, the exact (secret-redacted) arguments and a fingerprint; a version token for the target is read before the prompt and again after you answer, and the action is refused if it changed; a prompt nobody answers is a refusal. When the client can't elicit, the access-mode + flag gates above are the control — unless ANDROID_REQUIRE_HUMAN_APPROVAL=true, in which case destructive ops are refused instead.
Shell injection. adb shell joins its arguments into one string that the device's shell parses, so this server single-quotes every argument that reaches the device shell (one shared helper, src/adb/shell.ts) and passes adb exactly one string: text for input_text, URLs for open_url and alarm/timer messages are always literal data, and a read-write agent cannot use them to run commands or get around the ANDROID_ALLOW_SHELL gate (run_shell, which runs your string as-is by design, is the only exception). open_url additionally refuses any URL scheme other than http, https, tel, mailto, geo and market (plus ANDROID_EXTRA_URL_SCHEMES). input_text encodes spaces as %s and types a literal %s in two steps, because Android's input text would otherwise turn it into a space. See SECURITY.md.
Every tool also advertises MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so hosts can decide what to auto-approve.
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
android MCP questions
How do I add android MCP to Claude Code?
Run claude mcp add mcp-android -- npx -y @dockndevai/mcp-android in your terminal. Add --scope user to make it available in every project.
How do I add android MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does this work on iOS?
No, stock iPhones cannot be controlled this way due to Apple's sandbox restrictions. You should use the mcp-ios repository instead.
Do I need to root my Android phone?
No, the server does not require root access and is not installed on the phone itself.