emu-lab
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| EMU_ADB | No | Path to the adb executable. | |
| EMU_AVD | No | Name of the Android Virtual Device (AVD) to use. | unity-test |
| EMU_OWNER | No | Owner name for the emulator lease. | |
| ANDROID_HOME | No | Android SDK location on macOS and Linux. Ignored on Windows. | |
| EMU_LAB_HOME | No | Folder for leases, results, emulator logs, and configuration. | ~/.emu-lab |
| ANDROID_AVD_HOME | No | Android AVD location. | |
| ANDROID_SDK_ROOT | No | Android SDK location. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Self-test Unity Android builds on a local Android emulator (one AVD, default "unity-test"), shared safely by several AI sessions on this PC through a lease file.
Take the device first with emu_start (boots or reuses the AVD and leases it to this session). Every device-changing tool needs that lease.
BUSY means another session is using the emulator: do not install, tap or change anything; wait and try again later, or ask the person. Never release someone else's lease (only the person can, with the CLI emu-lab release --any-owner).
Always call emu_release when you are done (uninstall=true also removes the apps installed under the lease). emu_renew extends the lease (default 4 h) for long sessions.
emu_smoke installs an APK and checks it from outside the app: ready marker in logcat, crash or self-exit, ABI, system dialogs, tap, local notification in the shade and tapping back in. Its defaults are the bundled sample app's log lines (SMOKE_APP_READY, SMOKE_TAP count=1, SMOKE_NOTIF_SCHEDULED id= title=, SMOKE_OPENED_FROM_NOTIFICATION): for another app set ready_marker (a line your app logs when ready), no_tap or tap_marker, and notif_delay 0 unless it schedules a notification the same way.
emu_start, emu_smoke, emu_check_notification and emu_release run as jobs: if the call returns a job_id, call emu_job with that id (repeat while status is running). Never start the same tool again while its job runs; one device-changing job per AVD runs at a time.
emu_clock forward moves the device clock for long-delay notifications; always call emu_clock reset afterwards (if this server stops first, it puts the clock back itself).
Do not drive the device with mobile-mcp (or anything else using UiAutomation) while emu_smoke or emu_check_notification runs: they need UiAutomation for the notification shade and system dialogs.
Device audio stays off. emu_status and emu_screenshot change nothing and work without a lease.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| emu_statusA | Show the lease of the AVD (owner, until, valid, mine), the running emulators, the AVD's serial and boot state, the adb version and the resolved paths (SDK root, AVD home, adb, lab home). Changes nothing and needs no lease. If the lease belongs to another owner and is valid, the emulator is BUSY: wait or ask the person, do not use it. |
| emu_startA | Lease the AVD to this session and boot it (or reuse it when it already runs), then make it predictable for automation (animations off, screen stays on, keyguard dismissed, clock reset). Call this before any other device-changing tool. On BUSY another session holds the emulator: do not retry in a loop and never release its lease; wait, or ask the person. Runs as a job: if the result is a job_id, call emu_job with it. Calling it again under your own lease only renews the lease. Always call emu_release when done. |
| emu_renewA | Extend this session's lease of the AVD (default 4 hours from now), also after it ran out. Refused with NO_LEASE when there is no lease (take it with emu_start) and NOT_OWNER when the lease is another session's (then the emulator is busy: wait or ask the person). Does not touch the device. |
| emu_releaseA | Give back this session's lease when you are done: resets what test runs leave on the device (Firebase debug properties, a moved clock), uninstalls the apps installed under the lease when uninstall is true (or the listed packages), stops the emulator only if this lease started it (unless keep_running), then deletes the lease. Refused with NOT_OWNER for another session's lease: never try to release it, the person does that. No lease is not an error (released false). LEASE_CHANGED means another session took the lease over meanwhile: leave the emulator alone. Runs as a job: if the result is a job_id, call emu_job with it. |
| emu_smokeA | Install an APK on the leased emulator and self-test it from outside the app: ABI check, install, launch, wait for the ready marker in logcat (crash, ANR or self-exit fail the run), tap, background, local notification in the shade, tap it and check the app opens. Results (summary.json, logcat, screenshots) go to run_dir; check pass in the result. Needs this session's lease (emu_start first): NO_LEASE means take it, BUSY means another session uses the emulator (wait or ask the person). Defaults are the bundled sample app's log lines; for another app set ready_marker, no_tap or tap_marker, and notif_delay 0. Runs as a job: if the result is a job_id, call emu_job with it and do not start another smoke meanwhile. Do not use mobile-mcp while it runs. |
| emu_check_notificationA | Wait until a notification of the package whose title contains title is posted (dumpsys) and visible in the shade, optionally tap it and check the app opens (tap, opened_marker). Use it after the app scheduled a notification yourself (for example with emu_smoke notif_delay 0 and emu_clock forward). Needs this session's lease: NO_LEASE means emu_start first, BUSY means another session uses the emulator (wait or ask the person). Runs as a job: if the result is a job_id, call emu_job with it. Do not use mobile-mcp while it runs. |
| emu_clockA | action "forward" turns automatic time off and moves the device clock minutes ahead, so long-delay local notifications fire now (needs this session's lease: NO_LEASE means emu_start first). action "reset" puts the clock back to host time with automatic time on; it works without a lease and is refused only while another session holds the emulator (BUSY: wait or ask the person). After a forward always call reset, also when the check failed. |
| emu_screenshotA | Return a PNG screenshot of the AVD's screen (and its serial and size). Changes nothing and needs no lease; it works while another session holds the emulator, but then only look, do not act on it. |
| emu_jobA | Wait for a job started by emu_start, emu_smoke, emu_check_notification or emu_release (job_id from their result) and return its result once it finished, or its status and latest report lines while it still runs (then call emu_job again). Without job_id it lists this server's jobs. JOB_UNKNOWN means the id is not known to this server (jobs do not survive a server restart): list the jobs or check emu_status. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 9 tools
Most tools target a distinct resource+action: status/screenshot are read-only, start/renew/release manage the lease, clock manages time, job polls async work. The only blur is between emu_smoke (which includes a notification shade check) and emu_check_notification, but the descriptions explain when to use each (self-test pipeline vs. externally triggered notification after a clock forward).
All tools share a consistent emu_ prefix and snake_case formatting, which makes the set highly predictable. There is minor mixing between noun-style names (emu_status, emu_clock, emu_screenshot, emu_job) and verb-style names (emu_start, emu_renew, emu_release, emu_check_notification), but the pattern is still readable.
Nine tools is well-scoped for an emulator lab server: lease lifecycle (status/start/renew/release), test operations (smoke/notification/clock/screenshot), and async job polling. Each tool earns its place with no obvious filler.
The surface covers the full lease lifecycle plus testing, time control, screenshots, and job polling, so core automation workflows have no dead ends. Minor gaps exist: no standalone install-APK tool outside emu_smoke, and no reboot/wipe/reset-device operation, though these are workaroundable or out of scope.