# android-emulator-mcp

MCP server for managing local Android emulators (AVDs). Companion to [adb-mcp](https://github.com/JanJetze/adb-mcp) — this project handles emulator lifecycle, while adb-mcp handles device interaction.

## How it works

```
Claude Code ←→ android-emulator-mcp ←→ Android SDK tools (emulator, avdmanager, sdkmanager)
                                              ↓
                                        Local Android Emulator
                                              ↓
                                     adb-mcp (device interaction)
```

## Prerequisites

Install the Android command-line tools (requires Java):

```bash
brew install --cask temurin              # or any other JDK
brew install --cask android-commandlinetools
brew install --cask android-platform-tools
```

Homebrew installs `platform-tools` separately from the SDK root, but the emulator expects them together. Create a symlink:

```bash
ln -s /opt/homebrew/Caskroom/android-platform-tools/*/platform-tools \
      /opt/homebrew/share/android-commandlinetools/platform-tools
```

Set `ANDROID_HOME` in your shell:

```bash
export ANDROID_HOME="/opt/homebrew/share/android-commandlinetools"
```

## Setup

Add to your Claude Code MCP settings (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "android-emulator": {
      "command": "uvx",
      "args": ["android-emulator-mcp"]
    }
  }
}
```

Or install locally for development:

```json
{
  "mcpServers": {
    "android-emulator": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/android-emulator-mcp", "android-emulator-mcp"]
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `list_avds` | List all existing AVDs with their details |
| `create_avd` | Create a new AVD (auto-installs system image) |
| `delete_avd` | Delete an existing AVD |
| `start_emulator` | Start an AVD and wait for boot |
| `stop_emulator` | Stop a running emulator |
| `emulator_status` | Check which emulators are running |
| `list_system_images` | List available and installed system images |
| `sensor_status` | List all available sensors and their status |
| `sensor_get` | Get current values for a sensor |
| `sensor_set` | Set sensor values (acceleration, gyroscope, etc.) |

## Usage examples

- "Create an Android emulator and start it"
- "List my existing emulators"
- "Start the test emulator headless"
- "What system images do I have installed?"
- "Stop all running emulators"
- "Set the accelerometer to simulate the phone lying flat"
- "What sensors are available on the emulator?"

## Development

```bash
# Install dependencies
uv sync

# Run the server locally
uv run android-emulator-mcp

# Run tests
uv run pytest
```

## License

MIT