Hunt-Droid Mobile MCP

"Playwright for mobile" — as a Model Context Protocol server.

An MCP server that lets any MCP client (Claude Desktop, Claude Code, Cursor, or an agent framework like mamta) drive a real Android app, capture its API traffic, and test its mobile-native attack surface — the mobile analogue of the Playwright MCP used for the web.

It exposes 32 mobile_* tools over HTTP: open a device session (UI driving via the MobileRun accessibility layer + mitmproxy capture + Frida SSL-unpinning), drive the app by semantic locators, read the API traffic it produces, and replay/modify requests — exactly the surface an API-security agent (BOLA/BFLA/injection/mass-assignment/…) needs, sourced from a phone instead of a browser.

Extracted, self-contained, from the Hunt-Droid dynamic mobile-testing project. The internal Python package is named mamtamobile (Hunt-Droid's shared device core).

---

Architecture

  MCP client (Claude / mamta / Cursor)
        │  MCP over HTTP  (streamable-http or SSE)
        ▼
  Hunt-Droid Mobile MCP server   ── runs on the host where the phone is attached ──
        │
        ├── adb + MobileRun Portal (a11y)  →  get_ui / tap / type / scroll / find
        ├── am / content / dumpsys / logcat →  deeplinks, IPC, providers (attack surface)
        ├── mitmproxy (device global proxy) →  API traffic capture
        └── Frida                            →  SSL-unpinning (spawns the app)
        ▼
  Android device (USB or network-adb)

• HTTP transport because the physical device is on this host; the agent connects over the network. Default: streamable-http at http://<host>:8765/mcp.
• One device per server. A phone is a single resource; scale by running one server per device.
• Accessibility-tree driving (token-efficient, no vision model needed).

---

Install

Requires Python 3.10+, plus the runtime tooling on the host: adb, a connected Android device, mitmproxy, and Frida (frida-server on the device). The MobileRun Portal app must be installed on the device (accessibility driver).

git clone <this-repo> hunt-droid-mobile-mcp
cd hunt-droid-mobile-mcp
pip install -e .          # installs deps + the `mamtamobile-mcp` command

Traffic capture and SSL-unpinning are optional at runtime — without mitmproxy/Frida the server still drives the UI, it just won't capture HTTPS.

---

Run

adb devices                      # confirm a device is attached first
mamtamobile-mcp                  # or: python -m mamtamobile.mcp
# → mobile MCP server starting: transport=streamable-http host=0.0.0.0 port=8765

Configuration (all optional, via environment):

Var	Default	Meaning
MM_MCP_HOST	0.0.0.0	bind address (127.0.0.1 = localhost-only, safer)
MM_MCP_PORT	8765	port
MM_MCP_TRANSPORT	streamable-http	streamable-http or sse
MM_MCP_ALLOW_SHELL	0	1 exposes mobile_adb_shell (arbitrary adb — powerful)
MM_DEVICE_SERIAL	(auto)	pin a device serial (else the connected one / mobile_start_session's device arg)
MM_PROXY_PORT	18080	mitmproxy listen port
MM_FRIDA_ENABLED	1	SSL-unpinning on/off
MM_REPORT_DIR	reports	where captured traffic/artifacts are stored

Quick check it's up:

curl -s -X POST http://127.0.0.1:8765/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'
# → HTTP 200 + an SSE "event: message" reply

---

Tools

All tools are prefixed mobile_ so clients can namespace them (like Playwright's browser_). A typical flow: list_devices → start_session → find/tap → list_traffic → send_request.

Session

Tool	Purpose
mobile_list_devices()	List adb-connected devices (serials). Works with no session.
mobile_start_session(package, device?)	Open device, spawn app Frida-unpinned, start mitm capture. Call first.
mobile_stop_session() / mobile_session_status()	Tear down / inspect the session.

Drive the UI

Tool	Purpose
mobile_get_ui()	Numbered accessibility snapshot.
mobile_find(query, by?)	Locate elements by text / resource-id / content-desc / class.
mobile_tap_on(query, by?) / mobile_type_into(text, query?, by?)	Tap / type by what the element is, not a fragile index.
mobile_wait_for(text, timeout?, gone?)	Auto-poll until text appears/disappears.
mobile_scroll_to(text, dir?, max_swipes?)	Scroll until an element is on screen.
mobile_tap(i) / mobile_input_text(t,i?) / mobile_scroll(dir) / mobile_press_back() / mobile_open_app(pkg?)	Index-based driving.
mobile_screenshot()	PNG image content.
mobile_reset_app(package?)	pm clear — deterministic logout / clean slate.

Traffic (what an API-security agent consumes)

Tool	Purpose
mobile_list_traffic(limit?, method?, host?)	Distinct captured API requests — the attack surface.
mobile_get_traffic(id)	Full request+response for one entry.
mobile_send_request(method, url, headers?, body?)	Resend a (modified) request — the IDOR/BOLA/injection primitive.
mobile_action_traffic(settle?)	The requests your last UI action triggered (action→endpoint correlation).

Mobile-native attack surface

Tool	Purpose
mobile_attack_surface()	Enumerate deeplink schemes, exported components, provider authorities (dumpsys).
mobile_open_deeplink(uri)	Fire a deeplink / custom-scheme VIEW intent.
mobile_start_activity(component?, action?, data?, extras?)	Launch an Activity with a crafted intent.
mobile_send_broadcast(...) / mobile_start_service(component, extras?)	Exported receiver / service IPC PoCs.
mobile_query_provider(uri, projection?, where?)	Content-provider access-control / SQLi / traversal.
mobile_logcat(filter?, lines?)	Runtime evidence — leaked tokens, PoC confirmation.
mobile_current_activity() / mobile_list_apps(include_system?)	Orientation / target enumeration.
mobile_forensics()	Scan on-device storage (shared_prefs, dbs, files) for secrets.
mobile_adb_shell(command)	Arbitrary shell PoC — disabled unless MM_MCP_ALLOW_SHELL=1.

---

Connect a client

Claude Code

claude mcp add --transport http hunt-droid-mobile http://127.0.0.1:8765/mcp
# then /mcp shows the mobile_* tools

Claude Desktop

Custom connectors need HTTPS, but a local server is plain HTTP — bridge it with the Python mcp-proxy (no Node needed):

pip install --user mcp-proxy
# run the server in SSE mode:
MM_MCP_TRANSPORT=sse mamtamobile-mcp

claude_desktop_config.json:

{
  "mcpServers": {
    "hunt-droid-mobile": {
      "command": "mcp-proxy",
      "args": ["http://127.0.0.1:8765/sse"]
    }
  }
}

Restart Claude Desktop. (Or use npx mcp-remote http://127.0.0.1:8765/mcp if you have Node ≥ 20.)

mamta / any MCP client

mamta connects with a Go streamable-http MCP client and registers the mobile_* tools into its agent (mirroring its Playwright MCP integration). Point it at http://<host>:8765/mcp.

Then just ask: "start a session on com.example.app, log in, list the API traffic, and try swapping the order id in /orders/{id}."

---

Security

• No authentication. Fine on localhost / a trusted LAN. Before exposing it, bind MM_MCP_HOST=127.0.0.1 or put it behind an authenticated proxy — otherwise anyone on the network can drive your device.
• mobile_adb_shell is off by default. Only enable MM_MCP_ALLOW_SHELL=1 on a device you're authorized to test.
• Only test apps/devices you own or are authorized to assess. This tool drives real intents, replays real requests, and reads on-device storage.
• reports/ and .env are git-ignored (captured traffic contains tokens/PII).

---

Development

pip install -e ".[dev]"
python -m pytest tests/            # device-free: tools tested against an injected fake session
python -m mamtamobile.mcp          # run the server

The tests exercise tool registration + dispatch (session lifecycle, driving, semantic locators, traffic, attack-surface parsing, device listing) with a fake harness/portal — no device, mitmproxy, or LLM required.

Layout

mamtamobile/
  mcp/          # the MCP server (server.py) + entry point
  config.py     # env-based config
  explorer/     # mobile_tools.py — MobileRun device-tool harness
  device/       # portal.py — adb wrapper + Portal client (intents, providers, logcat)
  proxy/        # mitmproxy capture (setup + addon)
  instrument/   # Frida SSL-unpinning (pinning.py + ssl-bypass.js)
  forensics/    # on-device storage scan
  findings/     # per-session traffic + findings store
mobilerun/      # vendored MobileRun tool/UI source (device driving)
tests/