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).

Related MCP server: androir-mcp

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):

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

Drive the UI

Traffic (what an API-security agent consumes)

Mobile-native attack surface

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/