app_map

This tool on every surface: CLI · MCP · Python · JavaScript · Go · Java · .NET

Map the actionable elements on the current screen and return them as refs (@e1, @e2, ...) with a label and role. Call this before interacting, and again after anything that changes the screen — refs are only valid for the screen they were taken from. With diff, answer only what changed since the last map of this device: what appeared, what went away, and what changed label, checked state or place — what an action just did.

Read-only: readOnlyHint is true.

Arguments

Name	Type	Required	What it is
device	string		Device serial to target, e.g. "emulator-5554". Omit when only one device is running.
diff	boolean		Answer what changed since the last map of this device instead of the whole map. The first map of a session has nothing to compare with, so all of it is added, and first is set. Refs are the new map's; a removed element's are gone.
driver	string: uiautomator2, uiautomator, wda		Driver to use: "uiautomator2" (default for Android; fast, installs a server APK on first use), "uiautomator" (Android, installs nothing, slower, cannot type), or "wda" (WebDriverAgent: iOS simulators and iPhones).

Examples

Each is the arguments of a tools/call request; the first is shown whole.

Map what can be acted on, with a ref for each

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "app_map",
    "arguments": {}
  }
}

On an Android 15 emulator the answer's text was:

@e1 settings_homepage_container (list)
@e2 Profile picture, double tap to open Google Account (button)
@e3 Search settings (button)
@e4 main_content_scrollable_container (list)
@e5 Network & internet Mobile, Wi‑Fi, hotspot (button)
@e6 Connected devices Bluetooth, pairing (button)
@e7 Apps Assistant, recent apps, default apps (button)
@e8 Notifications Notification history, conversations (button)
@e9 Battery 100% (button)
@e10 Storage 51% used - 7.85 GB free (button)
@e11 Sound & vibration Volume, haptics, Do Not Disturb (button)

mobium map on an Android 15 emulator

What the last action changed

{
  "diff": true
}