# mobile-debug-mcp

[![CI](https://github.com/Techmanu-PVT-LTD/mobile-debug-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Techmanu-PVT-LTD/mobile-debug-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](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 Code driving a Flutter login screen on an Android emulator through mobile-debug-mcp](media/demo.gif)

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