アイリ Android

A MCP server that allows airi all LLMs to control Android devices. This project is a child project of airi.

Features

Input Control

• input_tap - Tap on the screen at given coordinates

• input_swipe - Swipe from one coordinate to another

• input_text - Input text on the device

• input_keyevent - Send a key event to the device

• input_press - Press the current key

• input_roll - Roll the trackball

Device Information

• wm_size - Get the physical screen size

• wm_density - Get the display density

• cpu_percent - Get CPU usage percentage

• cpu_count - Get the number of CPU cores

• battery_level - Get battery level

• battery_stats - Get detailed battery statistics

UI & Activity

• ui_get_hierarchy - Get UI hierarchy (XML)

• utils_top_activity - Get the top activity

• utils_top_activities - Get all top activities

• utils_package_version - Get package version info

Device Management

• device_connect - Connect to a device at specified host and port

• device_reset - Reset device connection

• shell_execute - Execute any shell command

Usage

Docker (Recommended)

docker run --rm -it -p 3000:3000 -e ADB_HOST=host.docker.internal ghcr.io/proj-airi/airi-android:v0.3.4
# or stdio mode
docker run --rm -i -e USE_STDIO=true -e ADB_HOST=host.docker.internal ghcr.io/proj-airi/airi-android:v0.3.4

For agents supporting MCP, you can use the following configuration:

// mcp.json
{
  "mcpServers": {
    // http mode
    "airi-android-http": {
      "url": "http://localhost:3000/mcp"
    },
    // stdio mode
    "airi-android-stdio": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "USE_STDIO=true",
        "-e",
        "ADB_HOST",
        "ghcr.io/proj-airi/airi-android:v0.3.4"
      ],
      "env": {
        "ADB_HOST": "host.docker.internal"
      }
    }
  }
}

Run Directly

Requires Bun to be installed.

# Install dependencies
bun install

# Start server (HTTP mode, port 3000)
bun run start

# Or use stdio mode
USE_STDIO=true bun run start

Development Setup

Prerequisites

1. Install Bun

2. Install Android Platform Tools

3. Connect an Android device (via USB or adb connect for emulators)

Commands

# Install dependencies
bun install

# Run tests
bun test

# Start development server
bun run dev

# Build binary
bun run build

# Lint code
bun run lint

# Type check
bun run typecheck

Contributing

See AGENTS.md for code guidelines.

Environment Variables

Tech Stack

• Bun - JavaScript runtime

• TypeScript - Type-safe JavaScript

• MCP SDK - Model Context Protocol SDK

• adbkit - ADB client library

• Hono - Web framework

• Zod - Schema validation

License

MIT