{
  "markdown": "# Android MCP Server\n\n> **The Android diagnostic & forensic MCP — when an app crashes, leaks memory, drains battery, or behaves unexpectedly, this is what you point at the device.**\n>\n> 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-health` aggregation. Pure ADB, no Appium / uiautomator2 dependency. 2-tier security (write + shell gates).\n\n[![npm](https://img.shields.io/npm/v/@us-all/android-mcp)](https://www.npmjs.com/package/@us-all/android-mcp)\n[![downloads](https://img.shields.io/npm/dm/@us-all/android-mcp)](https://www.npmjs.com/package/@us-all/android-mcp)\n[![tools](https://img.shields.io/badge/tools-76-blue)](#tools)\n[![@us-all standard](https://img.shields.io/badge/built%20to-%40us--all%20MCP%20standard-blue)](https://github.com/us-all/mcp-toolkit/blob/main/STANDARD.md)\n[![Glama MCP server](https://glama.ai/mcp/servers/us-all/android-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/us-all/android-mcp-server)\n\n## What it does that others don't\n\n- **Diagnostic depth** — logcat search/crash extraction, `dumpsys` (mem/gfx/cpu), getprop, processes, package internals, app intents, port forwards. Cross-platform competitors hide this surface.\n- **MCP Prompts** (5) — `crash-investigation`, `memory-leak-detection`, `ui-element-locator`, `app-startup-profile`, `permission-audit`. Workflow templates the model invokes directly.\n- **Aggregation tools** — `device-health` (battery + memory + cpu + network in one call), `analyze-app` (package info + memory + activities).\n- **2-tier security** — `ANDROID_MCP_ALLOW_WRITE` (gates installs/taps/pushes) and `ANDROID_MCP_ALLOW_SHELL` (gates arbitrary `adb shell`) are separate flags. Distinct trust levels.\n- **Pure ADB** — no Appium, no uiautomator2, no Python bridge. Just the official Android Debug Bridge wrapped over `child_process`.\n- **Token-efficient by design** — 56 schema-trim sweep, `ANDROID_TOOLS`/`ANDROID_DISABLE` 9 categories, `search-tools` meta.\n- **Apps SDK card** — `device-health` renders 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.\n- **stdio + Streamable HTTP** — defaults to stdio. Set `MCP_TRANSPORT=http` for ChatGPT Apps SDK or remote clients (Bearer auth via `MCP_HTTP_TOKEN`).\n\n## Try this — 5 prompts\n\nConnect the server to Claude Desktop or Claude Code, then paste any of these:\n\n1. **Crash investigation** — *\"My app `com.us-all.api` keeps crashing on this Pixel 6 emulator. Pull the last crash log, the offending stack frames, and any recent permission changes.\"*\n2. **Memory leak detection** — *\"Trace memory growth for `com.us-all.api` over the last 5 minutes. Show heap deltas, GC pressure, and the largest allocators.\"*\n3. **Battery drain attribution** — *\"What's draining battery on this device? Top 5 consumers, duration of each, and current battery health.\"*\n4. **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.\"*\n5. **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.\"*\n\n## When to use this vs mobile-next/mobile-mcp\n\n[`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp) (4.7K★) is the cross-platform action-oriented MCP. Different problem space:\n\n| | mobile-mcp | `@us-all/android-mcp` (this) |\n|--|---|---|\n| Platform | iOS + Android (cross-platform) | Android only (specialist) |\n| Posture | Action-oriented (\"drive the app via NL\") | Diagnostic (\"tell me why it broke\") |\n| UI surface | Accessibility-tree-first, action loops | UI hierarchy + screenshots + diagnostic dumps |\n| Diagnostic depth | minimal | logcat / dumpsys / getprop / processes / crashes |\n| Aggregations | — | `device-health`, `analyze-app` |\n| MCP Prompts | — | 5 (diagnostic-themed) |\n| Security gates | basic | 2-tier (write + shell separate) |\n| Distribution | broad (12+ IDE buttons) | npm + Docker |\n\n**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:\n- mobile-mcp finds the bug via UI exploration → this MCP captures the crash log + heap dump.\n- mobile-mcp can't tell you why startup is slow → this MCP gives you `dumpsys gfxinfo` + activity launch timing.\n- mobile-mcp can't reproduce a permission denial → this MCP shows the exact `dumpsys package` permission state and recent grants.\n\n## Install\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"android\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@us-all/android-mcp\"],\n      \"env\": {\n        \"ANDROID_MCP_ALLOW_WRITE\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add android -s user \\\n  -e ANDROID_MCP_ALLOW_WRITE=true \\\n  -e ANDROID_MCP_ALLOW_SHELL=true \\\n  -- npx -y @us-all/android-mcp\n```\n\n### Docker\n\n```bash\ndocker run --rm \\\n  --device /dev/bus/usb \\\n  -e ANDROID_MCP_ALLOW_WRITE=true \\\n  ghcr.io/us-all/android-mcp-server:latest\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/us-all/android-mcp-server.git\ncd android-mcp-server && pnpm install && pnpm build\nnode dist/index.js\n```\n\n### Prerequisites\n\n- ADB installed and on `PATH` (or set `ADB_PATH`)\n- Android device or emulator with USB debugging enabled\n- For multi-device setups: `ANDROID_SERIAL=<serial>` to target a specific one\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `ANDROID_HOME` | ❌ | auto-detect | Android SDK path |\n| `ADB_PATH` | ❌ | `adb` (PATH) | Path to ADB binary |\n| `ANDROID_SERIAL` | ❌ | auto (single device) | Target device serial |\n| `ANDROID_MCP_ALLOW_WRITE` | ❌ | `false` | Enable write operations (install, tap, push) |\n| `ANDROID_MCP_ALLOW_SHELL` | ❌ | `false` | Enable arbitrary `adb shell` execution |\n| `ANDROID_TOOLS` | ❌ | — | Comma-sep allowlist of categories. Biggest token saver. |\n| `ANDROID_DISABLE` | ❌ | — | Comma-sep denylist. Ignored when `ANDROID_TOOLS` is set. |\n| `MCP_TRANSPORT` | ❌ | `stdio` | `http` to enable Streamable HTTP transport |\n| `MCP_HTTP_TOKEN` | conditional | — | Bearer token. Required when `MCP_TRANSPORT=http` |\n| `MCP_HTTP_PORT` | ❌ | `3000` | HTTP listen port |\n| `MCP_HTTP_HOST` | ❌ | `127.0.0.1` | HTTP bind host (DNS rebinding protection auto-enabled for localhost) |\n| `MCP_HTTP_SKIP_AUTH` | ❌ | `false` | Skip Bearer auth — e.g. behind a reverse proxy that handles it |\n\n**Categories** (9): `device`, `apps`, `ui`, `logcat`, `emulator`, `files`, `system`, `debug`, `shell` (always-gated by `ANDROID_MCP_ALLOW_SHELL`), plus always-on `meta`.\n\nWhen `MCP_TRANSPORT=http`: `POST /mcp` (Bearer-auth JSON-RPC) + `GET /health` (public liveness).\n\n### Token efficiency\n\n| Scenario | Tools | Schema tokens | vs default |\n|----------|------:|--------------:|-----------:|\n| default (all categories) | 76 | 9,200 | — |\n| typical (`ANDROID_TOOLS=device,ui,apps,logcat`) | 37 | 5,000 | −46% |\n| narrow (`ANDROID_TOOLS=device,ui`) | 19 | **2,500** | **−73%** |\n\nPlus `search-tools` meta-tool (always enabled) for runtime tool discovery.\n\n### Read-only mode (default)\n\nBy 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.\n\n## MCP Prompts (5)\n\nWorkflow templates available via MCP `prompts/list`:\n\n- `crash-investigation` — pull crash logs + stack frames + recent permission changes for a target package.\n- `memory-leak-detection` — track heap delta over a window; cluster by allocator.\n- `ui-element-locator` — find a UI element by visual + accessibility hints; return tap coordinates.\n- `app-startup-profile` — cold-start profile: activity launch + fragment init + first frame.\n- `permission-audit` — flag dangerous permissions held by under-used 3rd-party apps.\n\n## MCP Resources\n\nURI-based read-only entities:\n\n- `android://devices` — connected devices\n- `android://device/{serial}` — device details (model/brand/version/display)\n- `android://app/{packageName}/activities` — activities exposed by a package (exported/launchable flags)\n- `android://device/{serial}/processes` — running processes\n\n## Tools (76)\n\n9 categories. Use `search-tools` to discover at runtime; full list collapsed below.\n\n| Category | Tools |\n|----------|------:|\n| System (battery / network / settings / display / orientation / port-fwd / wifi / mobile-data) | 19 |\n| Apps (install / launch / permissions / intents / data clear) | 14 |\n| UI (tap / swipe / screenshot / hierarchy / accessibility / annotated tap-by-index / screen recording) | 14 |\n| Emulator (AVD start/stop, snapshot mgmt) | 7 |\n| Device (list / info / properties / wireless connect) | 5 |\n| Debug (bugreport / mem / gfx / cpu / doctor) | 5 |\n| Logcat (capture / filter / clear / crash extract) | 4 |\n| Files (list / pull / push / delete) | 4 |\n| Shell (gated `execute-shell`) | 1 |\n| Aggregations (`device-health`, `analyze-app`) | 2 |\n| Meta (`search-tools`) | 1 |\n\n<details>\n<summary>Full tool list</summary>\n\n### Device (5)\n`list-devices`, `get-device-info`, `get-device-properties`, `connect-device`, `disconnect-device`\n\n### Apps (14)\n`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`\n\n### UI Automation (14)\n`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`\n\n### Logcat (4)\n`get-logcat`, `clear-logcat`, `search-logcat`, `get-crash-logs`\n\n### Emulator (7)\n`list-avds`, `start-emulator`, `stop-emulator`, `list-snapshots`, `load-snapshot`, `save-snapshot`, `delete-snapshot`\n\n### Files (4)\n`list-files`, `pull-file`, `push-file`, `delete-file`\n\n### System (19)\n`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`\n\n### Debug (5)\n`bugreport`, `get-mem-info`, `get-gfx-info`, `get-cpu-info`, `doctor`\n\n### Shell (1)\n`execute-shell` — gated by `ANDROID_MCP_ALLOW_SHELL`\n\n### Aggregations\n`device-health` — battery + memory + cpu + network in one call (~7KB response, 4 sub-systems with caveats).\n`analyze-app` — package info + memory + activities aggregation.\n\n### Meta\n`search-tools` — query other tools by keyword; always enabled.\n\n</details>\n\n## Architecture\n\n```\nClaude → MCP stdio → src/index.ts\n                      ├── adb.ts (execFile wrapper)\n                      ├── tools/utils.ts (wrapToolHandler, shellEscape, validation)\n                      └── tools/{device,apps,ui,logcat,emulator,files,system,debug,shell,aggregations}.ts\n                                  ↓\n                          ADB CLI (USB / TCP-IP / Emulator)\n                                  ↓\n                          Android Device\n```\n\nBuilt on [`@us-all/mcp-toolkit`](https://github.com/us-all/mcp-toolkit):\n- `extractFields` — token-efficient response projections (skipped for ADB flat-array endpoints)\n- `aggregate(fetchers, caveats)` — fan-out helper for `device-health` / `analyze-app`\n- `createWrapToolHandler` — `WriteBlockedError`/`ShellBlockedError` passthrough + structured ADB errors (`{code, stderr}`)\n- `wrapImageToolHandler` (Android-only) — base64 PNG sanitization\n- `search-tools` meta-tool\n\n## Security\n\n- **Read-only by default.** Writes blocked without `ANDROID_MCP_ALLOW_WRITE=true`.\n- **Shell gating separate.** `execute-shell` blocked without `ANDROID_MCP_ALLOW_SHELL=true` even with write enabled — distinct trust levels.\n- **Shell injection safe.** `shellEscape` for single-quote-based escape; input validation via zod regex whitelists for setting keys, package names, permissions, components, broadcast actions/extras.\n- **Path-traversal blocked.** Device paths require absolute + no `..` + no shell metachars.\n- **Error sanitization.** API keys, tokens, passwords redacted from all error outputs.\n\n## Tech stack\n\nNode.js 22+ • TypeScript strict ESM • pnpm 10 • `@modelcontextprotocol/sdk` 1.29+ • zod v4 • fast-xml-parser • vitest (fork pool isolation).\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 12951,
  "sha": "88ddb9afa8d38332fbb99456ea3177415f63952231c733813b23c61e4031b293",
  "repo_slug": "us-all/android-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_us_all_android_9196a2b4/readme"
}