Android MCP server
✓ VerifiedProvides deep diagnostic and forensic capabilities for Android devices using ADB to investigate crashes, memory leaks, and system performance.
Also known as us-all/android-mcp-server, android-mcp-server, @us-all/android-mcp
- Stars
- 16
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.14.4
- Last commit
- Jul 10, 2026
- License
- MIT
What is Android MCP?
Android provides deep diagnostic and forensic capabilities for Android devices using ADB to investigate crashes, memory leaks, and system performance.
Summary generated from the project's README
About Android MCP server
Investigating Android application crashes, memory leaks, and system performance is what developers achieve with this diagnostic and forensic MCP server. It provides deep access to device internals through 76 specialized tools covering logcat, dumpsys, package information, and system properties. Unlike cross-platform automation tools, this server focuses on technical root-cause analysis rather than just driving user interface actions.
Users connect the server to clients like Claude Desktop or Claude Code using stdio, or via remote HTTP transport with Bearer authentication. The setup requires ADB to be installed on the host machine and an Android device or emulator with USB debugging enabled. To manage security, the server uses a two-tier gate system where write operations and arbitrary shell commands must be explicitly enabled through separate environment variables.
Efficiency is a core design principle, offering tools to filter categories and reduce token usage. It includes built-in MCP prompts for specific workflows like crash investigation and permission audits. Specialized aggregation tools like device-health provide a single snapshot of battery, memory, CPU, and network status.
What you can do with it
- 1Investigate application crashesAnalyze stack frames and recent permission changes to determine why a specific package is failing.
- 2Detect memory leaksMonitor heap growth and allocator pressure over a set time window to find memory issues.
- 3Audit device permissionsIdentify third-party applications that hold sensitive permissions but are rarely used.
- 4Profile app startup performanceMeasure activity launch times and identify slow fragment initializations during cold starts.
- 5Monitor device healthGet a comprehensive overview of battery, memory, CPU, and network status in one request.
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 android-mcp-server -- npx -y @us-all/android-mcpInstall Android MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"android-mcp-server": {
"command": "npx",
"args": [
"-y",
"@us-all/android-mcp"
]
}
}
}Install Android MCP in VS Code
.vscode/mcp.json
{
"servers": {
"android-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@us-all/android-mcp"
]
}
}
}Install Android MCP in VS Code CLI
$ code --add-mcp '{"name":"android-mcp-server","type":"stdio","command":"npx","args":["-y","@us-all/android-mcp"]}'Install Android MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"android-mcp-server": {
"command": "npx",
"args": [
"-y",
"@us-all/android-mcp"
]
}
}
}Install Android MCP in Codex
$ codex mcp add android-mcp-server -- npx -y @us-all/android-mcpInstall Android MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.android-mcp-server] command = "npx" args = ["-y", "@us-all/android-mcp"]
Install Android MCP in Gemini CLI
$ gemini mcp add -s user android-mcp-server npx -- -y @us-all/android-mcpInstall Android MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"android-mcp-server": {
"command": "npx",
"args": [
"-y",
"@us-all/android-mcp"
]
}
}
}Configuration
ADB_PATHPath to adb binary. Default: 'adb' on PATH.
ANDROID_DISABLEComma-separated category disablelist.
ANDROID_HOMEAndroid SDK root. Used to resolve adb if ADB_PATH not set.
ANDROID_MCP_ALLOW_SHELLSet to 'true' to enable arbitrary shell command execution. Default disabled.
ANDROID_MCP_ALLOW_WRITESet to 'true' to enable write/destructive tools. Default read-only.
ANDROID_SERIALDefault device serial when multiple devices are connected.
ANDROID_TOOLSComma-separated category allowlist. Default: all categories enabled.
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 reachableus-all/android-mcp-server is public and reachablegithub.com/us-all/android-mcp-server ↗Pass
- Package names this repository as its source@us-all/android-mcp names us-all/android-mcp-server as sourcenpmjs.com/package/@us-all/android-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @us-all/android-mcpnpmjs.com/package/@us-all/android-mcp/v/1.14.4#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-10github.com/us-all/android-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @us-all/android-mcpPass
- No critical advisory in the package or its dependencies141 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 GitHubAndroid 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:
| mobile-mcp | @us-all/android-mcp (this) |
|
|---|---|---|
| Platform | iOS + Android (cross-platform) | Android only (specialist) |
| Posture | Action-oriented ("drive the app via NL") | Diagnostic ("tell me why it broke") |
| UI surface | Accessibility-tree-first, action loops | UI hierarchy + screenshots + diagnostic dumps |
| Diagnostic depth | minimal | logcat / dumpsys / getprop / processes / crashes |
| Aggregations | — | device-health, analyze-app |
| MCP Prompts | — | 5 (diagnostic-themed) |
| Security gates | basic | 2-tier (write + shell separate) |
| Distribution | broad (12+ IDE buttons) | npm + Docker |
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
| Variable | Required | Default | Description |
|---|---|---|---|
ANDROID_HOME |
❌ | auto-detect | Android SDK path |
ADB_PATH |
❌ | adb (PATH) |
Path to ADB binary |
ANDROID_SERIAL |
❌ | auto (single device) | Target device serial |
ANDROID_MCP_ALLOW_WRITE |
❌ | false |
Enable write operations (install, tap, push) |
ANDROID_MCP_ALLOW_SHELL |
❌ | false |
Enable arbitrary adb shell execution |
ANDROID_TOOLS |
❌ | — | Comma-sep allowlist of categories. Biggest token saver. |
ANDROID_DISABLE |
❌ | — | Comma-sep denylist. Ignored when ANDROID_TOOLS is set. |
MCP_TRANSPORT |
❌ | stdio |
http to enable Streamable HTTP transport |
MCP_HTTP_TOKEN |
conditional | — | Bearer token. Required when MCP_TRANSPORT=http |
MCP_HTTP_PORT |
❌ | 3000 |
HTTP listen port |
MCP_HTTP_HOST |
❌ | 127.0.0.1 |
HTTP bind host (DNS rebinding protection auto-enabled for localhost) |
MCP_HTTP_SKIP_AUTH |
❌ | false |
Skip Bearer auth — e.g. behind a reverse proxy that handles it |
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
| Scenario | Tools | Schema tokens | vs default |
|---|---|---|---|
| default (all categories) | 76 | 9,200 | — |
typical (ANDROID_TOOLS=device,ui,apps,logcat) |
37 | 5,000 | −46% |
narrow (ANDROID_TOOLS=device,ui) |
19 | 2,500 | −73% |
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.
| Category | Tools |
|---|---|
| System (battery / network / settings / display / orientation / port-fwd / wifi / mobile-data) | 19 |
| Apps (install / launch / permissions / intents / data clear) | 14 |
| UI (tap / swipe / screenshot / hierarchy / accessibility / annotated tap-by-index / screen recording) | 14 |
| Emulator (AVD start/stop, snapshot mgmt) | 7 |
| Device (list / info / properties / wireless connect) | 5 |
| Debug (bugreport / mem / gfx / cpu / doctor) | 5 |
| Logcat (capture / filter / clear / crash extract) | 4 |
| Files (list / pull / push / delete) | 4 |
Shell (gated execute-shell) |
1 |
Aggregations (device-health, analyze-app) |
2 |
Meta (search-tools) |
1 |
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).
License
Android MCP questions
How do I add Android MCP to Claude Code?
Run claude mcp add android-mcp-server -- npx -y @us-all/android-mcp 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 it require Appium or uiautomator2?
No, it uses pure ADB via child_process without any additional mobile automation dependencies.
How can I use this for crash investigation?
You can use the built-in crash-investigation prompt to pull crash logs, stack frames, and recent permission changes for a specific package.