# emulator-tools

MCP server that lets coding agents use iOS Simulators and Android Emulators.
One file, one dependency ([agent-device](https://github.com/callstackincubator/agent-device)).

The server exposes four tools. Driving the device (tap, type, read the screen,
install) goes through the `agent-device` CLI, which `device_open` hands back
already pinned to the device.

| Tool | What it does |
|---|---|
| `device_list` | Lists simulators and emulators, booted or not |
| `device_open` | Boots the device if needed; returns the `agent-device` command for it |
| `device_screenshot` | Returns a PNG of the screen |
| `device_close` | Ends the agent session; `shutdown: true` powers the device off |

The agent works from accessibility snapshots instead of guessing coordinates:

```sh
agent-device open com.android.settings --platform android --serial emulator-5554 --session emulator-tools-emulator-5554
agent-device snapshot -i ...   # @e1 [button] "Search settings" ...
agent-device press @e3 --settle ...
agent-device fill @e5 "text" --settle ...
```

## Requirements

- Node 20+
- iOS: macOS with Xcode and at least one simulator
- Android: SDK Platform-Tools and Emulator, plus an AVD. `ANDROID_HOME` is used
  when set, then `~/Library/Android/sdk`, then `adb` on `PATH`.

## Install

```sh
git clone https://github.com/mandaputtra/emulator-tools.git
cd emulator-tools
npm install
```

Add it to Claude Code:

```sh
claude mcp add emulator-tools -- node "$PWD/server.mjs"
```

Or to any MCP client config:

```json
{
  "mcpServers": {
    "emulator-tools": { "command": "node", "args": ["/absolute/path/to/emulator-tools/server.mjs"] }
  }
}
```

## Try it without an MCP client

```sh
node scripts/call.mjs device_list
node scripts/call.mjs device_open '{"deviceId":"Pixel_3a_API_34_Play"}'
node scripts/call.mjs device_screenshot '{"deviceId":"emulator-5554"}' shot.png
node scripts/call.mjs device_close '{"deviceId":"emulator-5554","shutdown":true}'
```

## Notes

- A stopped Android emulator is listed by its AVD name. After `device_open`
  boots it, its id becomes the adb serial (`emulator-5554`); the command
  `device_open` returns already uses the new id.
- The first iOS snapshot builds an XCTest runner, which takes a few minutes once.
- iOS screenshots are scaled to 1568px on the long edge to keep them small.

## Test

```sh
npm test
```

Protocol tests only; they need no device.

The tool design follows the device toolkit in T3 Code.

## License

MIT