Ramus

View saved version →

---
name: android-mcp
description: Runs an APK the person attaches, the Ramus demo app, an APK already uploaded to Ramus, or a GitHub pull request build on a disposable cloud Android emulator through Ramus's built-in tools (no terminal needed), then reads the screen, taps, types, swipes, takes screenshots and reads device logs, with a browser link a person can open to watch or take over. Use when asked to show, test, verify, reproduce or demo something on Android, or when a task needs a real Android device.
---

# Android emulator with Ramus (MCP tools)

The Ramus tools give you a disposable Android device in the cloud. Each
session starts fresh and is discarded when it ends or after 30 minutes idle.

## Checklist

```
- [ ] Start one session from the demo app, an uploaded APK or a pull request
- [ ] Give the person the watch link right away
- [ ] Drive the app: snapshot → act with ref + gen → snapshot again
- [ ] On failure, take a screenshot and read the logs before relaunching
- [ ] Show the person the result once with `android_show_screen`
- [ ] Report what you saw with the current watch link; end the session unless the person is still using it
```

## Start a device

Call `android_start_session` with exactly one source:

- `apk_file` for an APK the person attached to the conversation. Pass the
  attached file itself; Ramus downloads and installs it. Use this whenever
  the person attaches an `.apk`.
- `demo: true` for the Ramus sample app. Use this when the person has no app
  of their own to show.
- `apk_uri` for an APK the person already uploaded to Ramus (from the Ramus
  website or CLI).
- `pr: "owner/repo#123"` for a ready pull request build. It needs the Ramus
  GitHub App on the repository; if it is missing, call
  `android_install_github_app` and give the person the returned `setup_url`.
  Only a person can finish that setup; poll `android_install_status`.

The result has a `session` id and a `watch_url`. If the start times out, the
device keeps starting: poll `android_session_status`. `android_list_sessions`
shows the person's live sessions.

## Drive the app: observe, act, verify

1. **Observe.** `android_snapshot` returns the UI tree. Every element has a
   `ref` and the snapshot has a `gen`. Pass `find` to get only the elements
   matching a label. Labels can be in `contentDesc` rather than `text`.
2. **Act** with the values you just read: `android_tap` with `ref` and `gen`.
   Add `expect` (text that should appear) or `expect_gone` so the tap checks
   its own result.
3. **Verify** by taking a new snapshot before the next action. Every action
   and every snapshot makes old refs stale. Never invent a ref or a gen, and
   never chain several taps from one snapshot.

Other actions:

- `android_type` with `text` and a `ref` + `gen` focuses a field, replaces its
  contents and reads them back. `submit: true` presses Enter.
- `android_swipe` takes normalized coordinates (0 to 1): `y1: 0.8, y2: 0.2`
  scrolls down.
- `android_press` sends `BACK`, `HOME`, `ENTER`, `APP_SWITCH` or `IME_HIDE`.
  Repeated `BACK` can leave the app.
- `android_wait_for` waits for `text` to appear, `text_gone` to disappear, or
  `stable: true` (two matching snapshots).
- `android_app_launch` brings the app back after `HOME`, a crash or a
  reinstall.
- `android_camera_feed` shows a base64 image (PNG, JPEG or WebP, up to 8 MiB)
  on the back camera, for QR codes or photo uploads; `android_mic_feed` plays
  a base64 WAV into the microphone. `off: true` stops either. `in_use` means a
  person is streaming their own camera or microphone, which takes priority.

Take a new snapshot after each of these.

## When the tree is not enough

- Empty or incomplete tree: call `android_screenshot`, look at it, then tap
  with normalized `x` and `y`.
- Only use `force: true` on a non-clickable element after checking a
  screenshot.
- Crash or hang: call `android_logcat` and `android_screenshot` first, then
  `android_app_launch`. An accepted tap is not pr

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.