mobile-debug-mcp

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.

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.

Quickstart

With an emulator running and adb on your PATH:

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:

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)

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:

{ "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

uv run mobile-debug-mcp

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

uv run ruff check .
uv run ruff format .
uv run pytest          # no device needed — adb is faked, screens come from fixtures

See CONTRIBUTING.md for layout and conventions, and SECURITY.md before exposing the HTTP transport anywhere.

License

MIT © Techmanu Pvt. Ltd. — see LICENSE.

Maintained by @MaheshPhuyal02.