Android MCP Server
The Android diagnostic & forensic MCP — when an app crashes, leaks memory, drains battery, or behaves unexpectedly, this is what you point at the device.
76 tools across logcat / dumpsys / package internals / system properties / processes. 5 MCP Prompts (crash-investigation, memory-leak-detection, permission-audit, app-startup-profile, ui-element-locator) and a
device-healthaggregation. Pure ADB, no Appium / uiautomator2 dependency. 2-tier security (write + shell gates).
What it does that others don't
- Diagnostic depth — logcat search/crash extraction,
dumpsys(mem/gfx/cpu), getprop, processes, package internals, app intents, port forwards. Cross-platform competitors hide this surface. - MCP Prompts (5) —
crash-investigation,memory-leak-detection,ui-element-locator,app-startup-profile,permission-audit. Workflow templates the model invokes directly. - Aggregation tools —
device-health(battery + memory + cpu + network in one call),analyze-app(package info + memory + activities). - 2-tier security —
ANDROID_MCP_ALLOW_WRITE(gates installs/taps/pushes) andANDROID_MCP_ALLOW_SHELL(gates arbitraryadb shell) are separate flags. Distinct trust levels. - Pure ADB — no Appium, no uiautomator2, no Python bridge. Just the official Android Debug Bridge wrapped over
child_process. - Token-efficient by design — 56 schema-trim sweep,
ANDROID_TOOLS/ANDROID_DISABLE9 categories,search-toolsmeta. - Apps SDK card —
device-healthrenders as a snapshot card on ChatGPT clients (battery, RAM, Wi-Fi + 4-section grid) via_meta["openai/outputTemplate"]. Claude clients receive the same JSON content. - stdio + Streamable HTTP — defaults to stdio. Set
MCP_TRANSPORT=httpfor ChatGPT Apps SDK or remote clients (Bearer auth viaMCP_HTTP_TOKEN).
Try this — 5 prompts
Connect the server to Claude Desktop or Claude Code, then paste any of these:
- Crash investigation — "My app
com.us-all.apikeeps crashing on this Pixel 6 emulator. Pull the last crash log, the offending stack frames, and any recent permission changes." - Memory leak detection — "Trace memory growth for
com.us-all.apiover the last 5 minutes. Show heap deltas, GC pressure, and the largest allocators." - Battery drain attribution — "What's draining battery on this device? Top 5 consumers, duration of each, and current battery health."
- Permission audit — "Audit installed 3rd-party apps for dangerous permissions (location/camera/contacts/microphone). Flag any app that hasn't been used in the last 30 days but holds these."
- App startup profile — "Profile the cold-start of
com.us-all.api— measure activity launch time, identify the slowest fragment init, and suggest where to add tracing."
When to use this vs mobile-next/mobile-mcp
mobile-next/mobile-mcp (4.7K★) is the cross-platform action-oriented MCP. Different problem space:
Use both — they're complementary. mobile-mcp drives the device through your QA flows; this MCP tells you why it broke when something does. Especially:
- mobile-mcp finds the bug via UI exploration → this MCP captures the crash log + heap dump.
- mobile-mcp can't tell you why startup is slow → this MCP gives you
dumpsys gfxinfo+ activity launch timing. - mobile-mcp can't reproduce a permission denial → this MCP shows the exact
dumpsys packagepermission state and recent grants.
Install
Claude Desktop
{
"mcpServers": {
"android": {
"command": "npx",
"args": ["-y", "@us-all/android-mcp"],
"env": {
"ANDROID_MCP_ALLOW_WRITE": "true"
}
}
}
}
Claude Code
claude mcp add android -s user \
-e ANDROID_MCP_ALLOW_WRITE=true \
-e ANDROID_MCP_ALLOW_SHELL=true \
-- npx -y @us-all/android-mcp
Docker
docker run --rm \
--device /dev/bus/usb \
-e ANDROID_MCP_ALLOW_WRITE=true \
ghcr.io/us-all/android-mcp-server:latest
Build from source
git clone https://github.com/us-all/android-mcp-server.git
cd android-mcp-server && pnpm install && pnpm build
node dist/index.js
Prerequisites
- ADB installed and on
PATH(or setADB_PATH) - Android device or emulator with USB debugging enabled
- For multi-device setups:
ANDROID_SERIAL=<serial>to target a specific one
Configuration
Categories (9): device, apps, ui, logcat, emulator, files, system, debug, shell (always-gated by ANDROID_MCP_ALLOW_SHELL), plus always-on meta.
When MCP_TRANSPORT=http: POST /mcp (Bearer-auth JSON-RPC) + GET /health (public liveness).
Token efficiency
Plus search-tools meta-tool (always enabled) for runtime tool discovery.
Read-only mode (default)
By default, only read operations are permitted. Write operations (tap, install-app, push-file, etc.) return an error unless ANDROID_MCP_ALLOW_WRITE=true. Shell command execution requires a separate ANDROID_MCP_ALLOW_SHELL=true for additional security — even with write enabled, raw shell stays blocked unless this is explicitly set.
MCP Prompts (5)
Workflow templates available via MCP prompts/list:
crash-investigation— pull crash logs + stack frames + recent permission changes for a target package.memory-leak-detection— track heap delta over a window; cluster by allocator.ui-element-locator— find a UI element by visual + accessibility hints; return tap coordinates.app-startup-profile— cold-start profile: activity launch + fragment init + first frame.permission-audit— flag dangerous permissions held by under-used 3rd-party apps.
MCP Resources
URI-based read-only entities:
android://devices— connected devicesandroid://device/{serial}— device details (model/brand/version/display)android://app/{packageName}/activities— activities exposed by a package (exported/launchable flags)android://device/{serial}/processes— running processes
Tools (76)
9 categories. Use search-tools to discover at runtime; full list collapsed below.
Device (5)
list-devices, get-device-info, get-device-properties, connect-device, disconnect-device
Apps (14)
list-packages, get-package-info, install-app, uninstall-app, launch-app, stop-app, clear-app-data, grant-permission, revoke-permission, open-url, send-broadcast, get-current-activity, is-app-installed, get-app-intents
UI Automation (14)
take-screenshot, dump-ui-hierarchy, ui-snapshot-a11y, tap, long-press, swipe, input-text, press-key, drag-and-drop, start-screen-recording, pull-screen-recording, double-tap, take-annotated-screenshot, tap-element
Logcat (4)
get-logcat, clear-logcat, search-logcat, get-crash-logs
Emulator (7)
list-avds, start-emulator, stop-emulator, list-snapshots, load-snapshot, save-snapshot, delete-snapshot
Files (4)
list-files, pull-file, push-file, delete-file
System (19)
get-battery-info, get-network-info, change-setting, get-setting, set-display-size, set-display-density, keep-screen-on, port-forward, reverse-forward, list-forwards, remove-forward, toggle-wifi, toggle-mobile-data, open-notification, lock-device, unlock-device, get-orientation, set-orientation, list-settings
Debug (5)
bugreport, get-mem-info, get-gfx-info, get-cpu-info, doctor
Shell (1)
execute-shell — gated by ANDROID_MCP_ALLOW_SHELL
Aggregations
device-health — battery + memory + cpu + network in one call (~7KB response, 4 sub-systems with caveats).
analyze-app — package info + memory + activities aggregation.
Meta
search-tools — query other tools by keyword; always enabled.
Architecture
Claude → MCP stdio → src/index.ts
├── adb.ts (execFile wrapper)
├── tools/utils.ts (wrapToolHandler, shellEscape, validation)
└── tools/{device,apps,ui,logcat,emulator,files,system,debug,shell,aggregations}.ts
↓
ADB CLI (USB / TCP-IP / Emulator)
↓
Android Device
Built on @us-all/mcp-toolkit:
extractFields— token-efficient response projections (skipped for ADB flat-array endpoints)aggregate(fetchers, caveats)— fan-out helper fordevice-health/analyze-appcreateWrapToolHandler—WriteBlockedError/ShellBlockedErrorpassthrough + structured ADB errors ({code, stderr})wrapImageToolHandler(Android-only) — base64 PNG sanitizationsearch-toolsmeta-tool
Security
- Read-only by default. Writes blocked without
ANDROID_MCP_ALLOW_WRITE=true. - Shell gating separate.
execute-shellblocked withoutANDROID_MCP_ALLOW_SHELL=trueeven with write enabled — distinct trust levels. - Shell injection safe.
shellEscapefor single-quote-based escape; input validation via zod regex whitelists for setting keys, package names, permissions, components, broadcast actions/extras. - Path-traversal blocked. Device paths require absolute + no
..+ no shell metachars. - Error sanitization. API keys, tokens, passwords redacted from all error outputs.
Tech stack
Node.js 22+ • TypeScript strict ESM • pnpm 10 • @modelcontextprotocol/sdk 1.29+ • zod v4 • fast-xml-parser • vitest (fork pool isolation).
