mobile-debug-mcp

# mobile-debug-mcp [](https://github.com/Techmanu-PVT-LTD/mobile-debug-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/) An MCP server that lets Claude drive a real Android app on an emulator/device like a QA engineer: **launch, observe, act, verify** — with logs and screenshots as evidence. Unlike thin "adb over MCP" wrappers, every action returns the *new screen state* plus a *log delta*, so the output is not "I tapped a button", it's "I tapped **Sign in**, the app POSTed `/auth`, got a `401`, and showed an error toast — here's the screenshot and the log lines." It also **learns the app as it goes**. Every screen it sees becomes a node in a navigation map and every action an edge, so the second time you need Settings the agent takes a known route instead of re-exploring the UI — which is where the token cost in agentic QA actually goes. > Status: **early** — the primitive tool surface plus the app map and the first semantic > actions. Flutter canvas screens are handled via the semantics tree. See [PLAN.md](PLAN.md). ## Demo  Claude is asked to log out and log back in "and see if there are any errors". It reads the screen, taps its way through, and reports what the app *actually* did — no hand-written selectors. Full-quality recording: [`media/demo.mp4`](media/demo.mp4). ## Quickstart With an emulator running and `adb` on your `PATH`: ```bash uv sync --extra dev --extra images uv run mobile-debug-mcp --transport http # http://127.0.0.1:8765/mcp ``` Register it with Claude Code, then let the agent learn its way around: ```bash claude mcp add --transport http mobile-debug http://127.0.0.1:8765/mcp ``` ``` launch_app("com.example.app") → the landing screen, element-indexed, plus startup logs map_app() → crawls the app, bounded, building the navigation map get_map() → every screen it found and how each is reached navigate_to("Settings") → replays a known route: Home —[tap 'Menu']→ Drawer → Settings ``` `navigate_to("Settings", plan_only=True)` prints the route without touching the device. ## Requirements - Python 3.11+ - Android `platform-tools` on `PATH` (`adb`) - A running emulator or a USB-connected device Device selection: set `ANDROID_SERIAL`, or pass `--device <serial>`. With a single device connected, it is picked automatically; with zero or more than one and no selection, the server errors clearly. ## Run Two transports. Pick one. ### HTTP — a long-lived local daemon (recommended) ```bash uv run mobile-debug-mcp --transport http # http://127.0.0.1:8765/mcp ``` One daemon serves every project on the machine, so client config carries no absolute paths — commit this to any repo that wants the tools: ```json { "mcpServers": { "mobile-debug": { "type": "http", "url": "http://127.0.0.1:8765/mcp" } } } ``` The session outlives any single client, so the learned app map and logcat cursors persist across Claude sessions instead of being rebuilt each time. The trade: **you** start it — nothing auto-spawns it, and clients fail to connect while it's down. Because the surface is now network-reachable, HTTP mode tightens two things stdio got for free: - **Screenshot writes are sandboxed** to `~/.config/mobile-debug-mcp/artifacts` (`--artifacts-dir` to move it). `take_screenshot(save_path=…)` is otherwise an arbitrary-file-write primitive. - **DNS-rebinding protection is on**, so a web page in your browser can't POST to the port. The MCP SDK leaves this *off* by default; this server turns it on. Actions are serialised under a device lock — one device, one screen, so two concurrent clients can't interleave mid-action. That prevents corrupted actions, not logical races: two clients driving the same device still confuse each other, so don't. `--host` binds elsewhere, but there is **no authentication** — anyone who can reach the port can drive the device, read logcat (tokens, PII) and wipe app data. It warns if you bind beyond loopback. Don't, without putting auth in front of it. ### stdio — one process per client ```bash uv run mobile-debug-mcp ``` ```bash claude mcp add mobile-debug -- uv run --directory /abs/path/to/mobile-debug-mcp mobile-debug-mcp ``` Auto-spawned by the client, nothing to keep running — but the absolute path means the registration doesn't travel between machines, and state is rebuilt every session. `save_path` is unrestricted here, which is fine: the client already owns the process. ## Tools **Primitives** — every one returns the new screen state and the log delta it produced. | Tool | What it does | |---|---| | `launch_app` | force-stop → optional `pm clear` → launch; returns screen state | | `get_screen_state` | compact element list (+ optional downscaled screenshot) | | `tap_element` | tap by element id (or `x,y`); returns new state + log delta | | `input_text` | focus a field and type (ASCII for now) | | `take_screenshot` | pure image, no hierarchy dump — for canvas/Flutter/video screens | | `get_logs` | PID-scoped logcat, classified | | `press_key` | back / home / enter / … | | `swipe` | scroll / drag between two points | **App map** — navigate by learned route instead of re-exploring. | Tool | What it does | |---|---| | `map_app` | bounded auto-crawl that fills the map; skips destructive-looking controls | | `get_map` | every known screen and how each is reached | | `navigate_to` | declares a route, then replays it, re-resolving elements by selector | **Semantic** — deterministic sense→act→verify state machines. | Tool | What it does | |---|---| | `reset_app` | restart or clear-and-restart, then verify where it actually landed | | `go_home` | route → unwind the back stack → relaunch, cheapest first; never blind-presses | ## Development ```bash uv run ruff check . uv run ruff format . uv run pytest # no device needed — adb is faked, screens come from fixtures ``` See [CONTRIBUTING.md](CONTRIBUTING.md) for layout and conventions, and [SECURITY.md](SECURITY.md) before exposing the HTTP transport anywhere. ## License MIT © [Techmanu Pvt. Ltd.](https://github.com/Techmanu-PVT-LTD) — see [LICENSE](LICENSE). Maintained by [@MaheshPhuyal02](https://github.com/MaheshPhuyal02).