# android-mcp

<!-- mcp-name: io.github.ouchi-dev/android-mcp -->

Let Claude, or any [MCP](https://modelcontextprotocol.io) assistant, see an Android
phone's screen and use it, over plain `adb`. No app to install on the phone, no root.

*Laisser Claude voir l'écran d'un téléphone Android et s'en servir, par adb, sans rien
installer sur le téléphone.*

What it is good for:

- **Testing your own app** like a user would: *"open my app, create an account, tell me
  where it breaks"*, then read the crash in `logcat`.
- **Repetitive phone chores**: *"go through my notifications settings and turn off every
  shopping app"*.
- **Accessibility**: describing a screen and acting on it by voice through the assistant.

## How it sees the screen

`screen_elements` turns the phone's accessibility tree into a short list: every visible
text and every touchable element, with its centre, type, id and state (checked, disabled,
editable...). The assistant then taps by name with `tap_element("Wi-Fi")`. That is
cheaper and much more reliable than guessing coordinates on a screenshot; `screenshot`
is there for layout, images and games.

## Tools

| Tool | |
|---|---|
| `devices` | Phones and emulators adb can see |
| `screen_elements`, `screenshot`, `current_app` | Read the screen |
| `tap_element`, `tap`, `swipe`, `type_text`, `press_key` | Act on it |
| `list_apps`, `launch_app`, `install_apk` | Apps |
| `logcat` | Recent log, per app, errors only if wanted |

There is deliberately **no free shell tool**: every action is named and bounded, and the
server's instructions ask the assistant to check with you before sending messages,
paying or deleting anything.

## Install

1. On the phone: *Settings > About > tap Build number 7 times*, then *Developer options >
   USB debugging* (or *Wireless debugging*). Plug it in and accept the prompt.
2. On the computer, with [platform-tools](https://developer.android.com/tools/releases/platform-tools)
   installed (`adb devices` should list the phone):

With [uv](https://docs.astral.sh/uv/) installed, nothing else is needed:

```bash
claude mcp add android -- uvx android-mcp-lite
```

Or with pip: `pip install android-mcp-lite`, then `claude mcp add android -- android-mcp`.

With several devices, pass `serial` (from `devices`) to each tool. Set `ADB` if adb is
not on the PATH or in `~/Android/Sdk/platform-tools`.

## Status

Version 0.1, tested on an Android 14 emulator: reading the screen, screenshots, launching
apps, tapping by name, scrolling, typing and keys. `install_apk` and `logcat` are written
but not yet exercised on a device.

- [x] Screen as a list of elements, tap by name
- [x] Retries while the screen is still animating
- [ ] Unicode typing (accents, emoji) through a clipboard helper
- [ ] Wait for an element to appear
- [ ] Record a session and replay it as a test
- [ ] Notifications: read and act on them

## License

MIT