Airi Android

GitHub

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

Variable	Description	Default
USE_STDIO	Set to true to use stdio transport mode	false
ADB_HOST	ADB server host address	localhost

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