アイリ Android MCP

アイリ Android

一个 MCP 服务，可让airi所有大模型控制 Android 设备。此项目是 airi 的子项目。

功能

输入控制

• input_tap - 点击指定坐标处的屏幕
• input_swipe - 从一个坐标滑动到另一个坐标
• input_text - 在设备上输入文本
• input_keyevent - 向设备发送按键事件
• input_press - 按下当前按键
• input_roll - 滚动轨迹球

设备信息

• wm_size - 获取物理屏幕尺寸
• wm_density - 获取显示密度
• cpu_percent - 获取 CPU 使用率
• cpu_count - 获取 CPU 核心数
• battery_level - 获取电池电量
• battery_stats - 获取详细的电池统计信息

UI 和活动

• ui_get_hierarchy - 获取 UI 层级结构（XML）
• utils_top_activity - 获取顶部活动
• utils_top_activities - 获取所有顶部活动
• utils_package_version - 获取软件包版本信息

设备管理

• device_connect - 连接到指定主机和端口上的设备
• device_reset - 重置设备连接
• shell_execute - 执行任意 shell 命令

用法

Docker（推荐）

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

对于支持 MCP 的 Agent，可以使用以下配置：

// 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"
      }
    }
  }
}

直接运行

需要安装 Bun。

# Install dependencies
bun install

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

# Or use stdio mode
USE_STDIO=true bun run start

开发环境设置

前置条件

1. 安装 Bun
2. 安装 Android Platform Tools
3. 连接 Android 设备（通过 USB，或使用 adb connect 连接模拟器）

命令

# 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

贡献

代码指南请参阅 AGENTS.md。

环境变量

变量	描述	默认值
USE_STDIO	设置为 true 以使用 stdio 传输模式	false
ADB_HOST	ADB 服务主机地址	localhost

技术栈

• Bun - JavaScript 运行时
• TypeScript - 类型安全的 JavaScript
• MCP SDK - Model Context Protocol SDK
• adbkit - ADB 客户端库
• Hono - Web 框架
• Zod - 模式验证

许可证

MIT